Skip to main content

​
Core Settings

​
PORT

Default: 3000 HTTP server port. 
PORT=8080

​
HOST

Default: 0.0.0.0 Bind address for the HTTP server. 
HOST=127.0.0.1  # Localhost only
HOST=0.0.0.0    # All interfaces

​
NODE_ENV

Default: production Node.js environment mode. 
NODE_ENV=production
NODE_ENV=development

​
DATA_DIR

Default: /app/data (Docker) or ./data (local) Directory for persistent data (database, stacks, git repos, cache). 
DATA_DIR=/custom/path/to/data

​
User and Permissions

​
PUID

Default: 1001 User ID for the Dockhand process (Docker only). 
PUID=1000

​
PGID

Default: 1001 Group ID for the Dockhand process (Docker only). 
PGID=1000

​
Database

​
DATABASE_URL

Default: SQLite at $DATA_DIR/db/dockhand.db PostgreSQL connection string. Omit to use SQLite. 
DATABASE_URL=postgres://user:password@localhost:5432/dockhand
DATABASE_URL=postgresql://user:password@host:5432/database?sslmode=require
See Database Configuration for details.

​
DB_FAIL_ON_MIGRATION_ERROR

Default: true Exit immediately if database migrations fail. 
DB_FAIL_ON_MIGRATION_ERROR=false  # Continue anyway (dangerous)

​
DB_VERBOSE_LOGGING

Default: false Enable verbose database logging. 
DB_VERBOSE_LOGGING=true

​
SKIP_MIGRATIONS

Default: false Skip database migrations on startup (debugging only). 
SKIP_MIGRATIONS=true

​
Docker Connection

​
DOCKER_SOCKET

Default: Auto-detected (/var/run/docker.sock) Path to the Docker socket. 
DOCKER_SOCKET=/var/run/docker.sock
DOCKER_SOCKET=/custom/path/to/docker.sock

​
DOCKER_HOST

Default: None Docker daemon connection URL. 
DOCKER_HOST=unix:///var/run/docker.sock
DOCKER_HOST=tcp://192.168.1.100:2375
DOCKER_HOST=tcp://192.168.1.100:2376

​
DOCKER_API_VERSION

Default: Auto-negotiated Docker API version to use. 
DOCKER_API_VERSION=1.43

​
HOST_DATA_DIR

Default: Auto-detected Host path to DATA_DIR for Docker bind mounts. 
HOST_DATA_DIR=/host/path/to/data

​
HOST_DOCKER_SOCKET

Default: Auto-detected Host path to Docker socket for stack deployment. 
HOST_DOCKER_SOCKET=/var/run/docker.sock

​
Security

​
ENCRYPTION_KEY

Default: Auto-generated and saved to $DATA_DIR/.encryption_key 32-byte hex key for encrypting sensitive data (passwords, tokens, TLS keys). 
ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
Important: Back up this key. If lost, encrypted data cannot be recovered.
Generate a new key: 
openssl rand -hex 32
Default: Auto-detected (HTTPS = true, HTTP = false) Force secure cookies. 
COOKIE_SECURE=true   # Require HTTPS
COOKIE_SECURE=false  # Allow HTTP

​
DISABLE_LOCAL_LOGIN

Default: false Disable local username/password login (force SSO). 
DISABLE_LOCAL_LOGIN=true

​
Hostname

​
DOCKHAND_HOSTNAME

Default: Auto-detected from Docker API Hostname for license validation and display. 
DOCKHAND_HOSTNAME=my-docker-host

​
HOSTNAME

Default: Container hostname Container hostname (used for host path detection). 
HOSTNAME=dockhand-prod

​
Performance

​
COMPOSE_TIMEOUT

Default: 900 (15 minutes) Timeout in seconds for Docker Compose operations. 
COMPOSE_TIMEOUT=1800  # 30 minutes

​
SKIP_DF_COLLECTION

Default: false Skip disk usage collection (use if df command is slow). 
SKIP_DF_COLLECTION=true

​
MEMORY_MONITOR

Default: false Enable memory monitoring and heap snapshots. 
MEMORY_MONITOR=true

​
SNAPSHOT_INTERVAL

Default: 60 (minutes) Interval for memory snapshots when MEMORY_MONITOR=true. 
SNAPSHOT_INTERVAL=30  # 30 minutes

​
Event Collection

​
DISABLE_METRICS

Default: false Disable metrics collection (CPU, memory, disk). 
DISABLE_METRICS=true

​
DISABLE_EVENTS

Default: false Disable container event collection. 
DISABLE_EVENTS=true

​
Git Integration

​
GIT_REPOS_DIR

Default: $DATA_DIR/git-repos Directory for cloned Git repositories. 
GIT_REPOS_DIR=/custom/git/repos

​
Timezone

​
TZ

Default: UTC Timezone for logs and timestamps. 
TZ=America/New_York
TZ=Europe/London
TZ=Asia/Tokyo

​
Example Configuration

​
Docker Compose with PostgreSQL

docker-compose.yaml
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: dockhand
      POSTGRES_PASSWORD: secure-password
      POSTGRES_DB: dockhand
    volumes:
      - postgres_data:/var/lib/postgresql/data

  dockhand:
    image: fnsys/dockhand:latest
    ports:
      - 3000:3000
    environment:
      # Database
      DATABASE_URL: postgres://dockhand:secure-password@postgres:5432/dockhand
      
      # Security
      ENCRYPTION_KEY: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
      COOKIE_SECURE: "true"
      
      # User
      PUID: 1000
      PGID: 1000
      
      # Performance
      COMPOSE_TIMEOUT: 1800
      
      # Timezone
      TZ: America/New_York
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data
    depends_on:
      - postgres

volumes:
  postgres_data:
  dockhand_data:

​
Environment File (.env)

.env
# Core
PORT=3000
NODE_ENV=production
DATA_DIR=/app/data

# Database
DATABASE_URL=postgres://dockhand:password@postgres:5432/dockhand
DB_FAIL_ON_MIGRATION_ERROR=true

# Security
ENCRYPTION_KEY=your-32-byte-hex-key-here
COOKIE_SECURE=true

# User
PUID=1000
PGID=1000

# Docker
DOCKER_SOCKET=/var/run/docker.sock

# Performance
COMPOSE_TIMEOUT=900
SKIP_DF_COLLECTION=false

# Timezone
TZ=UTC

​
Best Practices

Use .env Files

Store sensitive variables in .env files, not in docker-compose.yaml.

Back Up Keys

Back up ENCRYPTION_KEY and .encryption_key file. Without them, encrypted data is lost.

Set Timeouts

Increase COMPOSE_TIMEOUT for large stacks that take time to deploy.

Use PostgreSQL

For production, use PostgreSQL instead of SQLite for better performance and reliability.

​
Validation

Check current environment variables: 
# In running container
docker exec dockhand env | grep -E "(PORT|DATABASE_URL|ENCRYPTION_KEY)"

# In compose
docker compose config
Test database connection: 
docker exec dockhand node -e "console.log(process.env.DATABASE_URL ? 'PostgreSQL' : 'SQLite')"

Build docs developers (and LLMs) love

Get started for freeTalk to us