Docker Deployment

Run Dockhand with Docker

Quick Start

Pull and run the latest Dockhand image:

docker run -d \
  --name dockhand \
  --restart unless-stopped \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  fnsys/dockhand:latest

Access Dockhand at http://localhost:3000

Image Details

The official Dockhand Docker image is based on a security-hardened Wolfi OS with minimal attack surface:

• Base OS: Custom Wolfi (built with apko)
• Runtime: Node.js 24 (from official node:24-slim)
• Architecture: Multi-arch (amd64, arm64)
• Size: ~350MB
• User: Non-root by default (UID 1001)

Pre-installed Tools

The image includes these packages:

• docker-cli - Docker command-line client
• docker-compose - Docker Compose V2
• docker-cli-buildx - Docker Buildx plugin
• sqlite - SQLite database (default database)
• postgresql-client - PostgreSQL client (for external databases)
• git - Git version control
• openssh-client + openssh-keygen - SSH support for Git
• curl - HTTP client for health checks

Configuration

Port Mapping

Dockhand listens on port 3000 by default. Change the host port:

docker run -d \
  -p 8080:3000 \
  # ... other options
  fnsys/dockhand:latest

Data Persistence

Mount a volume or bind mount to persist data:

Named volume (recommended):

-v dockhand_data:/app/data

Bind mount:

-v /host/path/to/data:/app/data

The data directory contains:

• db/ - SQLite database (if not using PostgreSQL)
• stacks/ - Compose file backups
• git-repos/ - Cloned Git repositories
• scanner-cache/ - Vulnerability scanner databases
• tmp/ - Temporary files (TLS certificates, etc.)

Docker Socket

Dockhand requires access to the Docker socket to manage containers:

-v /var/run/docker.sock:/var/run/docker.sock

Mounting the Docker socket gives Dockhand full control over Docker. Only expose Dockhand to trusted users.

User and Permissions

Default User (UID 1001)

By default, Dockhand runs as user dockhand (UID 1001, GID 1001). The entrypoint automatically adds this user to the Docker socket’s group.

Custom UID/GID

Change the user ID at runtime:

docker run -d \
  -e PUID=1000 \
  -e PGID=1000 \
  # ... other options
  fnsys/dockhand:latest

Run as Root

To run as root:

docker run -d \
  -e PUID=0 \
  -e PGID=0 \
  # ... other options
  fnsys/dockhand:latest

User Directive (Rootless)

Use Docker’s user: directive:

docker run -d \
  --user 1000:1000 \
  --group-add $(stat -c '%g' /var/run/docker.sock) \
  # ... other options
  fnsys/dockhand:latest

When using --user, you must manually add the Docker socket group with --group-add.

Environment Variables

See Environment Variables for a complete list.

Health Check

The image includes a built-in health check:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/ || exit 1

Check container health:

docker inspect --format='{{.State.Health.Status}}' dockhand

Resource Limits

Set memory and CPU limits:

docker run -d \
  --memory=512m \
  --cpus=1 \
  # ... other options
  fnsys/dockhand:latest

Networking

Bridge Network (Default)

Default bridge network allows container communication:

docker run -d \
  --network bridge \
  # ... other options
  fnsys/dockhand:latest

Custom Network

Create a custom network:

docker network create dockhand-net

docker run -d \
  --network dockhand-net \
  # ... other options
  fnsys/dockhand:latest

Host Network

Use host networking (not recommended for security):

docker run -d \
  --network host \
  -e PORT=3000 \
  # ... other options
  fnsys/dockhand:latest

Updates

Update to the latest version:

# Pull latest image
docker pull fnsys/dockhand:latest

# Stop and remove old container
docker stop dockhand
docker rm dockhand

# Start new container
docker run -d \
  --name dockhand \
  --restart unless-stopped \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  fnsys/dockhand:latest

Dockhand supports self-update from the web UI (Settings > System > Self-Update).

Emergency Scripts

The image includes emergency scripts for recovery:

# Reset database
docker exec dockhand /app/scripts/emergency/reset-db.sh

# Clear cache
docker exec dockhand /app/scripts/emergency/clear-cache.sh

Logs

View container logs:

# Follow logs
docker logs -f dockhand

# Last 100 lines
docker logs --tail 100 dockhand

# Logs since timestamp
docker logs --since 2024-01-01T00:00:00 dockhand

Troubleshooting

Permission Denied on Docker Socket

If you see “permission denied” errors:

1. Check socket permissions:

   ls -la /var/run/docker.sock
   

2. Add user to docker group:

   docker exec dockhand sh -c 'addgroup dockhand $(stat -c %g /var/run/docker.sock)'
   

3. Restart container:

   docker restart dockhand
   

Container Won’t Start

Check logs for errors:

docker logs dockhand

Common issues:

• Port 3000 already in use (change with -p 8080:3000)
• Data volume permissions (fix with chown -R 1001:1001 /path/to/data)
• Docker socket not mounted

Database Locked

If using SQLite and seeing “database locked” errors:

1. Stop Dockhand
2. Check for other processes accessing the database
3. Restart Dockhand

For production, consider PostgreSQL.