Quick Start

Get started with Dockhand in minutes

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

Step 1: Deploy Dockhand

Docker Compose (Recommended)

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

Docker Run

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.

Step 2: First Login

1. Access Web Interface

   Open your browser and navigate to:

   http://localhost:3000
   

   You’ll see the Dockhand login page.

2. Register Admin Account

   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.

3. Login

   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

1. Navigate to Containers

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

2. 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
3. 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

Deploy New Container

1. Navigate to Container Creation

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

2. Configure Container

   Fill in the basic settings:

   Example: Nginx Web Server

   Name: my-nginx
   Image: nginx:latest
   Ports: 8080:80
   Restart Policy: unless-stopped
   
3. 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
4. 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.

1. Navigate to Stacks

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

2. 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
3. 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:
   
4. Deploy Stack

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

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

   Monitor deployment progress in real-time.

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

1. Open Logs View

   Navigate to any container and click “Logs” tab.

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

Interactive Terminal

1. Open Terminal

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

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

File Browser

1. Open File Browser

   Navigate to any container and click “Files” tab.

2. Browse Filesystem

   • Navigate directories by clicking folder names
   • View file contents by clicking file names
   • Upload files from your computer
   • Download files to your computer
   • Delete files and directories

File operations respect container permissions. Some paths may be read-only.

Step 7: Configure Remote Docker Hosts

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

1. Navigate to Environments

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

2. 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
3. Test Connection

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

   • Docker version
   • Host OS and architecture
   • Total resources (CPU, memory)
4. 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)

1. Navigate to Auth Settings

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

2. 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
3. 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 Users

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?

1. Navigate to Stacks → Select your stack
2. Click “Edit” to modify the Docker Compose file
3. Click “Save & Redeploy”
4. 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"