π³ 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 β
Create a dedicated project directory:
bashmkdir -p shellguard && cd shellguardGenerate 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 24Create
docker-compose.ymlin the directory:yamlservices: 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 β
Launch the stack in detached mode:
bashdocker compose up -d --waitConfirm reef health:
bashcurl 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_TOKENfor 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
.envexports.
| Environment Variable | Required | Default | Description |
|---|---|---|---|
PORT | No | 6565 | The HTTP/HTTPS port the Express server listens on inside the container. |
DATA_DIR | Yes | /app/data | Path to persistent storage containing db.sqlite, audit.sqlite, certs/, and instance.key. |
DB_ENCRYPTION_KEY | Yes | (Empty) | 256-bit Base64 key for per-row metadata encryption (Layer 2) and SQLCipher whole-DB encryption (Layer 3). |
ADMIN_TOKEN | Yes | (Empty) | Authentication token for the SuperLobster control plane at /superlobster. |
PUID / PGID | No | 1000:1000 | Host user/group IDs for permissions remapping. Set to 99:100 on Unraid. |
TRUST_PROXY | No | false | Enable (true) if running behind a reverse proxy terminating TLS (Nginx, Caddy, Traefik). |
TLS_ENABLED | No | false | When true, enables Native LAN TLS with automatic 10-year EC P-256 self-signed cert generation. See First-Class HTTPS & TLS. |
DISABLE_SIGNUPS | No | false | When true, closes public registration. Identity creation requires a single-use SuperLobster invite token (?invite=inv_...). Genesis User #1 is immune. |
TLS_CERT_PATH | No | (Empty) | Absolute path to external public certificate for Bring-Your-Own (BYO) TLS mode. |
TLS_KEY_PATH | No | (Empty) | Absolute path to external private key for Bring-Your-Own (BYO) TLS mode. |
CORS_ORIGIN | No | (Empty) | Restricts cross-origin resource sharing to designated domain origins. |
TOKEN_TTL_DEFAULT | No | 24h | Default expiration lifetime for user session tokens (1h, 24h, 7d). |
ATTACHMENT_MAX_MB | No | 500 | Per-file attachment upload ceiling in MB (clamped 1β2000MB; pre-stream Content-Length 413 check). |
GROTTO_QUOTA_MB | No | 1000 | Total 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:
- Independent
PUID&PGIDRemapping: Uses POSIX integer validation (''|*[!0-9]*)) to validate host user and group IDs. Remapsnodeuser (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. - Safe
DATA_DIRFallback: IfDATA_DIRis unset or contains whitespace, the entrypoint and backend connection safely fall back to/app/data(in-container default) or./data(host default). - Volume Ownership Verification: Enforces
chown -Ron the target data directory to ensure SQLite can write its WAL, SHM, and database lock files without host filesystem friction. - Privilege Dropping: Drops root privileges using
su-execto execute the Node.js process as the non-privilegednodeuser.