> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Finsys/dockhand/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Configuration options for Dockhand

## Core Settings

### PORT

**Default**: `3000`

HTTP server port.

```bash theme={null}
PORT=8080
```

### HOST

**Default**: `0.0.0.0`

Bind address for the HTTP server.

```bash theme={null}
HOST=127.0.0.1  # Localhost only
HOST=0.0.0.0    # All interfaces
```

### NODE\_ENV

**Default**: `production`

Node.js environment mode.

```bash theme={null}
NODE_ENV=production
NODE_ENV=development
```

### DATA\_DIR

**Default**: `/app/data` (Docker) or `./data` (local)

Directory for persistent data (database, stacks, git repos, cache).

```bash theme={null}
DATA_DIR=/custom/path/to/data
```

## User and Permissions

### PUID

**Default**: `1001`

User ID for the Dockhand process (Docker only).

```bash theme={null}
PUID=1000
```

### PGID

**Default**: `1001`

Group ID for the Dockhand process (Docker only).

```bash theme={null}
PGID=1000
```

## Database

### DATABASE\_URL

**Default**: SQLite at `$DATA_DIR/db/dockhand.db`

PostgreSQL connection string. Omit to use SQLite.

```bash theme={null}
DATABASE_URL=postgres://user:password@localhost:5432/dockhand
DATABASE_URL=postgresql://user:password@host:5432/database?sslmode=require
```

See [Database Configuration](/deployment/database) for details.

### DB\_FAIL\_ON\_MIGRATION\_ERROR

**Default**: `true`

Exit immediately if database migrations fail.

```bash theme={null}
DB_FAIL_ON_MIGRATION_ERROR=false  # Continue anyway (dangerous)
```

### DB\_VERBOSE\_LOGGING

**Default**: `false`

Enable verbose database logging.

```bash theme={null}
DB_VERBOSE_LOGGING=true
```

### SKIP\_MIGRATIONS

**Default**: `false`

Skip database migrations on startup (debugging only).

```bash theme={null}
SKIP_MIGRATIONS=true
```

## Docker Connection

### DOCKER\_SOCKET

**Default**: Auto-detected (`/var/run/docker.sock`)

Path to the Docker socket.

```bash theme={null}
DOCKER_SOCKET=/var/run/docker.sock
DOCKER_SOCKET=/custom/path/to/docker.sock
```

### DOCKER\_HOST

**Default**: None

Docker daemon connection URL.

```bash theme={null}
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.

```bash theme={null}
DOCKER_API_VERSION=1.43
```

### HOST\_DATA\_DIR

**Default**: Auto-detected

Host path to `DATA_DIR` for Docker bind mounts.

```bash theme={null}
HOST_DATA_DIR=/host/path/to/data
```

### HOST\_DOCKER\_SOCKET

**Default**: Auto-detected

Host path to Docker socket for stack deployment.

```bash theme={null}
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).

```bash theme={null}
ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
```

<Warning>
  **Important**: Back up this key. If lost, encrypted data cannot be recovered.
</Warning>

Generate a new key:

```bash theme={null}
openssl rand -hex 32
```

### COOKIE\_SECURE

**Default**: Auto-detected (HTTPS = true, HTTP = false)

Force secure cookies.

```bash theme={null}
COOKIE_SECURE=true   # Require HTTPS
COOKIE_SECURE=false  # Allow HTTP
```

### DISABLE\_LOCAL\_LOGIN

**Default**: `false`

Disable local username/password login (force SSO).

```bash theme={null}
DISABLE_LOCAL_LOGIN=true
```

## Hostname

### DOCKHAND\_HOSTNAME

**Default**: Auto-detected from Docker API

Hostname for license validation and display.

```bash theme={null}
DOCKHAND_HOSTNAME=my-docker-host
```

### HOSTNAME

**Default**: Container hostname

Container hostname (used for host path detection).

```bash theme={null}
HOSTNAME=dockhand-prod
```

## Performance

### COMPOSE\_TIMEOUT

**Default**: `900` (15 minutes)

Timeout in seconds for Docker Compose operations.

```bash theme={null}
COMPOSE_TIMEOUT=1800  # 30 minutes
```

### SKIP\_DF\_COLLECTION

**Default**: `false`

Skip disk usage collection (use if `df` command is slow).

```bash theme={null}
SKIP_DF_COLLECTION=true
```

### MEMORY\_MONITOR

**Default**: `false`

Enable memory monitoring and heap snapshots.

```bash theme={null}
MEMORY_MONITOR=true
```

### SNAPSHOT\_INTERVAL

**Default**: `60` (minutes)

Interval for memory snapshots when `MEMORY_MONITOR=true`.

```bash theme={null}
SNAPSHOT_INTERVAL=30  # 30 minutes
```

## Event Collection

### DISABLE\_METRICS

**Default**: `false`

Disable metrics collection (CPU, memory, disk).

```bash theme={null}
DISABLE_METRICS=true
```

### DISABLE\_EVENTS

**Default**: `false`

Disable container event collection.

```bash theme={null}
DISABLE_EVENTS=true
```

## Git Integration

### GIT\_REPOS\_DIR

**Default**: `$DATA_DIR/git-repos`

Directory for cloned Git repositories.

```bash theme={null}
GIT_REPOS_DIR=/custom/git/repos
```

## Timezone

### TZ

**Default**: `UTC`

Timezone for logs and timestamps.

```bash theme={null}
TZ=America/New_York
TZ=Europe/London
TZ=Asia/Tokyo
```

## Example Configuration

### Docker Compose with PostgreSQL

```yaml docker-compose.yaml theme={null}
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)

```bash .env theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Use .env Files" icon="file">
    Store sensitive variables in `.env` files, not in `docker-compose.yaml`.
  </Card>

  <Card title="Back Up Keys" icon="key">
    Back up `ENCRYPTION_KEY` and `.encryption_key` file. Without them, encrypted data is lost.
  </Card>

  <Card title="Set Timeouts" icon="clock">
    Increase `COMPOSE_TIMEOUT` for large stacks that take time to deploy.
  </Card>

  <Card title="Use PostgreSQL" icon="database">
    For production, use PostgreSQL instead of SQLite for better performance and reliability.
  </Card>
</CardGroup>

## Validation

Check current environment variables:

```bash theme={null}
# In running container
docker exec dockhand env | grep -E "(PORT|DATABASE_URL|ENCRYPTION_KEY)"

# In compose
docker compose config
```

Test database connection:

```bash theme={null}
docker exec dockhand node -e "console.log(process.env.DATABASE_URL ? 'PostgreSQL' : 'SQLite')"
```