Quick Start

This guide walks you through deploying Dockhand, creating your first user, and managing your first container.

Step 1: Deploy Dockhand

Docker Compose (Recommended)
Docker Run

Create a docker-compose.yaml file:

docker-compose.yaml

services:
  dockhand:
    image: fnsys/dockhand:latest
    container_name: dockhand
    restart: unless-stopped
    ports:
      - 3000:3000
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data

volumes:
  dockhand_data:

Start Dockhand:

docker compose up -d

Check the logs:

docker compose logs -f dockhand

Run Dockhand with a single command:

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

Check the logs:

docker logs -f dockhand

Wait for the message “Database migrations completed successfully” in the logs before proceeding.

Access Web Interface

Open your browser and navigate to:

http://localhost:3000

You’ll see the Dockhand login page.

Click “Create Account” or “Register” and fill in:

Username: Your admin username (e.g., admin)
Password: Strong password (minimum 8 characters)
Confirm Password: Re-enter your password

The first user to register automatically becomes the administrator with full access to all features.

Use your newly created credentials to log in. You’ll be redirected to the Dockhand dashboard.

Step 3: Explore the Dashboard

After logging in, you’ll see the main dashboard with:

Real-time Metrics: CPU, memory, and disk usage
Container Stats: Running, stopped, and total containers
Image Count: Total Docker images on your system
Volume and Network Stats: Storage and networking information
Recent Activity: Latest container and stack events

The dashboard updates in real-time using WebSocket connections. No page refresh needed!

Step 4: Manage Your First Container

View Existing Containers
Deploy New Container

Navigate to Containers

Click “Containers” in the left sidebar to see all containers on your Docker host.

View Container Details

Click on any container to see:

Container status and health
Resource usage (CPU, memory, network I/O)
Environment variables
Port mappings
Volume mounts
Network connections

Interact with Container

Available actions:

Start/Stop/Restart: Control container lifecycle
Logs: View real-time logs with search and filtering
Terminal: Open an interactive shell inside the container
Files: Browse and manage container filesystem
Stats: View detailed resource metrics

Navigate to Container Creation

Click “Containers” → ”+ New Container” button.

Configure Container

Fill in the basic settings:

Example: Nginx Web Server

Name: my-nginx
Image: nginx:latest
Ports: 8080:80
Restart Policy: unless-stopped

Advanced Options (Optional)

Configure additional settings:

Environment Variables: Key-value pairs
Volumes: Bind mounts or named volumes
Networks: Connect to specific Docker networks
Labels: Metadata for organization
Resources: CPU and memory limits

Create and Start

Click “Create” to deploy the container. It will start automatically and appear in your container list.

Step 5: Deploy Your First Stack

Stacks allow you to deploy multi-container applications using Docker Compose.

Navigate to Stacks

Click “Stacks” in the left sidebar, then click ”+ New Stack”.

Create Stack Configuration

Enter stack details:

Name: my-first-stack
Editor: Choose between:
- Compose Editor: Write Docker Compose YAML
- Form Editor: Visual form-based configuration

Add Compose Content

Here’s a simple example with WordPress and MySQL:

docker-compose.yml

services:
  db:
    image: mysql:8.0
    volumes:
      - db_data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: somewordpress
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress
    restart: unless-stopped

  wordpress:
    image: wordpress:latest
    ports:
      - 8080:80
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
      WORDPRESS_DB_NAME: wordpress
    depends_on:
      - db
    restart: unless-stopped

volumes:
  db_data:

Deploy Stack

Click “Deploy” or “Create & Start”. Dockhand will:

Validate the Docker Compose syntax
Create the stack directory
Pull required images (if not available)
Create networks and volumes
Start all services in dependency order

Monitor deployment progress in real-time.

Verify Deployment

Once deployed:

Stack status shows as “Running”
All services appear in the stack detail view
Access WordPress at http://localhost:8080

Change default passwords in production deployments. The example above uses weak passwords for demonstration only.

Step 6: View Logs and Terminal

Container Logs
Interactive Terminal
File Browser

Open Logs View

Navigate to any container and click “Logs” tab.

Use Log Features

Real-time streaming: Logs update automatically
Search: Filter logs by keyword
Timestamps: Toggle timestamp display
Tail lines: Limit number of lines shown
Download: Export logs to file

Open Terminal

Navigate to any running container and click “Terminal” tab.

Execute Commands

You’ll get an interactive shell (usually /bin/sh or /bin/bash) inside the container.Try some commands:

# View running processes
ps aux

# Check disk usage
df -h

# View network configuration
ip addr

# Install packages (if needed)
apt-get update && apt-get install -y curl

Terminal sessions are ephemeral. Changes made inside the container are lost unless you commit them or use volumes.

Step 7: Configure Remote Docker Hosts

Dockhand supports managing multiple Docker hosts (local and remote).

Navigate to Environments

Click “Settings” → “Environments” in the sidebar.

Add Remote Host

Click ”+ Add Environment” and configure:

Name: Friendly name (e.g., Production Server)
Connection:
- Socket: Local Docker socket (default)
- TCP: Remote Docker daemon (e.g., tcp://192.168.1.100:2376)
- SSH: Docker over SSH tunnel
TLS: Upload certificates if using TLS-protected Docker daemon

Test Connection

Click “Test Connection” to verify connectivity. You should see:

Docker version
Host OS and architecture
Total resources (CPU, memory)

Switch Between Environments

Use the environment selector in the top navigation bar to switch between Docker hosts.

All Dockhand features (containers, stacks, images, volumes) work identically across all environments.

Step 8: Enable Authentication (Optional)

For production deployments, configure SSO or additional authentication methods.

OIDC (SSO)
Local Users

Navigate to Auth Settings

Go to “Settings” → “Authentication” → “OIDC Providers”.

Add OIDC Provider

Click ”+ Add Provider” and configure:

Provider Name: Display name (e.g., Keycloak, Azure AD)
Client ID: From your IdP
Client Secret: From your IdP
Issuer URL: Your IdP’s issuer endpoint
Redirect URI: http://your-dockhand-url/api/auth/oidc/callback

Test and Enable

Click “Test Connection”, then “Enable” if successful.

Users can now log in using your SSO provider. First login auto-creates their account.

Local username/password authentication is enabled by default.To disable local auth and require SSO:

docker-compose.yaml

services:
  dockhand:
    image: fnsys/dockhand:latest
    environment:
      DISABLE_LOCAL_LOGIN: "true"
    # ... other config

Ensure you have a working SSO provider configured before disabling local login.

Next Steps

Configuration

Explore all environment variables and advanced configuration options

Git Integration

Deploy stacks from Git repositories with auto-sync and webhooks

Scheduling

Automate container operations with cron-based scheduling

API Reference

Integrate Dockhand with your automation tools using the REST API

Common Tasks

How do I update a running stack?

Navigate to Stacks → Select your stack
Click “Edit” to modify the Docker Compose file
Click “Save & Redeploy”
Dockhand will perform a rolling update (or recreate containers if needed)

How do I back up my data?

SQLite (default):

# Backup data volume
docker run --rm \
  -v dockhand_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/dockhand-backup.tar.gz /data

PostgreSQL:

# Backup database
docker exec dockhand-postgres pg_dump -U dockhand dockhand > backup.sql

How do I view all containers across environments?

Use the Dashboard for a unified view, or switch environments using the selector in the top navigation bar.

Can I use Dockhand with Portainer?

Yes! Dockhand and Portainer can coexist on the same Docker host. They use the Docker API independently and don’t interfere with each other.

How do I upgrade Dockhand?

# Pull latest image
docker pull fnsys/dockhand:latest

# Restart with new image
docker compose down
docker compose up -d

Database migrations run automatically on startup.

Troubleshooting

I can't access the Docker socket

Symptom: Dockhand shows “No Docker connection” or permission errors.Solution:

# Find Docker socket group
stat -c '%g' /var/run/docker.sock

# Add group to container
docker run -d \
  --name dockhand \
  --group-add [GID] \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  fnsys/dockhand:latest

Stack deployment fails

Common causes:

Invalid Docker Compose syntax
Missing required images
Port conflicts
Insufficient resources

Solution: Check stack logs in the UI or run:

docker logs dockhand

Web UI is slow or unresponsive

Possible causes:

Many containers (>100)
Slow Docker daemon
Synology NAS with disk usage collection enabled

Solution: Disable disk metrics collection on Synology:

services:
  dockhand:
    environment:
      SKIP_DF_COLLECTION: "true"

Overview

Getting Started

Core Features

Advanced Features

Authentication & Security

Deployment

Integrations

Step 1: Deploy Dockhand

Step 3: Explore the Dashboard

Step 4: Manage Your First Container

Step 5: Deploy Your First Stack

Step 6: View Logs and Terminal

Step 7: Configure Remote Docker Hosts

Step 8: Enable Authentication (Optional)

Next Steps

Configuration

Git Integration

Scheduling

API Reference

Common Tasks

Troubleshooting

Build docs developers (and LLMs) love

Overview

Getting Started

Core Features

Advanced Features

Authentication & Security

Deployment

Integrations

​Step 1: Deploy Dockhand

​Step 2: First Login

​Step 3: Explore the Dashboard

​Step 4: Manage Your First Container

​Step 5: Deploy Your First Stack

​Step 6: View Logs and Terminal

​Step 7: Configure Remote Docker Hosts

​Step 8: Enable Authentication (Optional)

​Next Steps

Configuration

Git Integration

Scheduling

API Reference

​Common Tasks

​Troubleshooting

Build docs developers (and LLMs) love

Step 1: Deploy Dockhand

Step 2: First Login

Step 3: Explore the Dashboard

Step 4: Manage Your First Container

Step 5: Deploy Your First Stack

Step 6: View Logs and Terminal

Step 7: Configure Remote Docker Hosts

Step 8: Enable Authentication (Optional)

Next Steps

Common Tasks

Troubleshooting