Skip to content

🐳 Docker & Container Deployment ​

ShellGuard is distributed as a single unified container image on GitHub Container Registry (ghcr.io/clawstackstudios/shellguard). The container bundles the production-compiled React frontend and the Express 5 backend into a hardened node:20-alpine runtime.


πŸš€ Rapid Deployment with Docker Compose ​

Step 1: Configure & Generate Keys ​

  1. Create a dedicated project directory:

    bash
    mkdir -p shellguard && cd shellguard
  2. Generate the master database encryption key and SuperLobster admin token:

    bash
    # Generate 256-bit DB Encryption Key (Layer 2 metadata & Layer 3 SQLCipher)
    openssl rand -base64 32
    
    # Generate secure SuperLobster Admin Token
    openssl rand -hex 24
  3. Create docker-compose.yml in the directory:

    yaml
    services:
      shellguard:
        image: ghcr.io/clawstackstudios/shellguard:latest
        container_name: shellguard
        restart: unless-stopped
        ports:
          - "6464:6464"
        volumes:
          - ./data:/app/data
        environment:
          - NODE_ENV=production
          - PORT=6464
          - DATA_DIR=/app/data
          - DB_ENCRYPTION_KEY=your_generated_base64_key_here
          - ADMIN_TOKEN=your_superlobster_admin_token_here
          - PUID=1000
          - PGID=1000
          - TRUST_PROXY=false
        healthcheck:
          test: ["CMD", "wget", "-qO-", "http://localhost:6464/api/health"]
          interval: 15s
          timeout: 10s
          retries: 5
          start_period: 15s

Step 2: Start & Verify the Container ​

  1. Launch the stack in detached mode:

    bash
    docker compose up -d --wait
  2. Confirm reef health:

    bash
    curl http://localhost:6464/api/health

Step 3: Launch Vault & Access Control Planes ​

  • Sovereign Web Vault: Open http://localhost:6464 to molt your 67-character hu- master identity key.
  • SuperLobster Control Plane: Open http://localhost:6464/superlobster and log in with your configured ADMIN_TOKEN for system telemetry, scheduled snapshot management, and user administration.

βš™οΈ Environment Configuration Reference ​

πŸ’‘ Need the full catalog with one-click copy buttons? Explore the Interactive Docker Environment Variables Reference for the complete 24-variable matrix, instant search, and sample .env exports.

Environment VariableRequiredDefaultDescription
PORTNo6565The HTTP/HTTPS port the Express server listens on inside the container.
DATA_DIRYes/app/dataPath to persistent storage containing db.sqlite, audit.sqlite, certs/, and instance.key.
DB_ENCRYPTION_KEYYes(Empty)256-bit Base64 key for per-row metadata encryption (Layer 2) and SQLCipher whole-DB encryption (Layer 3).
ADMIN_TOKENYes(Empty)Authentication token for the SuperLobster control plane at /superlobster.
PUID / PGIDNo1000:1000Host user/group IDs for permissions remapping. Set to 99:100 on Unraid.
TRUST_PROXYNofalseEnable (true) if running behind a reverse proxy terminating TLS (Nginx, Caddy, Traefik).
TLS_ENABLEDNofalseWhen true, enables Native LAN TLS with automatic 10-year EC P-256 self-signed cert generation. See First-Class HTTPS & TLS.
DISABLE_SIGNUPSNofalseWhen true, closes public registration. Identity creation requires a single-use SuperLobster invite token (?invite=inv_...). Genesis User #1 is immune.
TLS_CERT_PATHNo(Empty)Absolute path to external public certificate for Bring-Your-Own (BYO) TLS mode.
TLS_KEY_PATHNo(Empty)Absolute path to external private key for Bring-Your-Own (BYO) TLS mode.
CORS_ORIGINNo(Empty)Restricts cross-origin resource sharing to designated domain origins.
TOKEN_TTL_DEFAULTNo24hDefault expiration lifetime for user session tokens (1h, 24h, 7d).
ATTACHMENT_MAX_MBNo500Per-file attachment upload ceiling in MB (clamped 1–2000MB; pre-stream Content-Length 413 check).
GROTTO_QUOTA_MBNo1000Total per-owner grotto storage quota in MB (clamped 1–100000MB; breaches reject with HTTP 413).

πŸ”’ Security & Non-Root Execution ​

The container includes a hardened entrypoint script (docker-entrypoint.sh) that executes prior to dropping privileges and launching Node.js:

  1. Independent PUID & PGID Remapping: Uses POSIX integer validation (''|*[!0-9]*)) to validate host user and group IDs. Remaps node user (PUID) and group (PGID) independently, ensuring environments like Unraid (PUID=99, PGID=100) or custom NAS storage groups apply group permissions even if UID is unchanged.
  2. Safe DATA_DIR Fallback: If DATA_DIR is unset or contains whitespace, the entrypoint and backend connection safely fall back to /app/data (in-container default) or ./data (host default).
  3. Volume Ownership Verification: Enforces chown -R on the target data directory to ensure SQLite can write its WAL, SHM, and database lock files without host filesystem friction.
  4. Privilege Dropping: Drops root privileges using su-exec to execute the Node.js process as the non-privileged node user.

Sovereign Zero-Knowledge Secrets Vault. Released under AGPL-3.0. β€’ Privacy Policy