Skip to main content

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us