Dockhand User Manual

Welcome to Dockhand, a modern, powerful Docker management application. This manual covers all features and functionality to help you get the most out of Dockhand.

Quick start

Get Dockhand running in minutes with Docker:

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:v1.0.0

Or using Docker Compose:

services:
  dockhand:
    image: fnsys/dockhand:v1.0.0
    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:

Then open http://localhost:3000 in your browser.

Docker socket permissions

Dockhand needs access to Docker to manage containers. By default, the Dockhand container runs as a non-root user, which may not have permission to access the socket on your host system.

If you see a "permission denied" error when trying to add your local environment, you'll need to configure socket access. Here are the options:

# Find the Docker group ID on your host (Linux)
stat -c '%g' /var/run/docker.sock
# On macOS, use: stat -f '%g' /var/run/docker.sock
# Example output: 999

# Run Dockhand with the matching group
docker run -d \
  --name dockhand \
  --restart unless-stopped \
  --group-add 999 \
  -p 3000:3000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  fnsys/dockhand:v1.0.0

services:
  dockhand:
    image: fnsys/dockhand:v1.0.0
    container_name: dockhand
    restart: unless-stopped
    group_add:
      - "999"  # Replace with your host's Docker GID
    ports:
      - "3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data

volumes:
  dockhand_data:

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

services:
  dockhand:
    image: fnsys/dockhand:v1.0.0
    container_name: dockhand
    restart: unless-stopped
    user: "0:0"
    ports:
      - "3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data

volumes:
  dockhand_data:

# NOT RECOMMENDED - makes socket accessible to everyone
sudo chmod 666 /var/run/docker.sock

services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy
    container_name: socket-proxy
    restart: unless-stopped
    environment:
      # Required for Dockhand core functionality
      - CONTAINERS=1
      - IMAGES=1
      - NETWORKS=1
      - VOLUMES=1
      - EVENTS=1
      - POST=1
      - DELETE=1
      # Optional: enable for terminal access
      # - EXEC=1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - socket-proxy

  dockhand:
    image: fnsys/dockhand:v1.0.0
    container_name: dockhand
    restart: unless-stopped
    depends_on:
      - socket-proxy
    ports:
      - "3000:3000"
    volumes:
      - dockhand_data:/app/data
    networks:
      - socket-proxy
      - default

networks:
  socket-proxy:
    internal: true

volumes:
  dockhand_data:

Recommendations by environment

Home lab or private server behind a VPN (Tailscale/WireGuard):

Option 1 (GID matching) or Option 2 (root) is acceptable. The risk is manageable assuming your network is secure and you trust the Dockhand application code.

Public-facing server or production environment:

Consider using a Socket Proxy (Option 4) or restricting access via a VPN.

Security summary

* Higher than direct socket access, but actual security depends on proxy configuration (which API endpoints are enabled) and container hardening.

Platform notes

Deployment examples

Behind a reverse proxy (Traefik)

When running behind Traefik or another reverse proxy, you don't need to expose ports directly:

services:
  dockhand:
    image: fnsys/dockhand:v1.0.0
    container_name: dockhand
    restart: unless-stopped
    user: "0:0"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data
    networks:
      - proxy  # Must match your Traefik network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.dockhand.rule=Host(`dockhand.example.com`)"
      - "traefik.http.routers.dockhand.entrypoints=websecure"
      - "traefik.http.routers.dockhand.tls=true"
      - "traefik.http.routers.dockhand.tls.certresolver=letsencrypt"
      - "traefik.http.services.dockhand.loadbalancer.server.port=3000"
      - "traefik.docker.network=proxy"  # Required if container has multiple networks

networks:
  proxy:
    external: true  # Assumes Traefik network already exists

volumes:
  dockhand_data:

With Nginx reverse proxy

Example Nginx configuration for proxying to Dockhand:

server {
    listen 443 ssl http2;
    server_name dockhand.example.com;

    ssl_certificate /etc/ssl/certs/dockhand.crt;
    ssl_certificate_key /etc/ssl/private/dockhand.key;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

With Tailscale (VPN-only access)

The simplest and usually most secure approach: Traefik listens on 80/443, but ports are only accessible within your Tailnet (no public port exposure on the host).

services:
  tailscale:
    image: tailscale/tailscale:latest
    hostname: homelab-gw
    environment:
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_STATE_DIR=/var/lib/tailscale
    volumes:
      - tailscale_state:/var/lib/tailscale
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - net_admin
      - sys_module
    restart: unless-stopped

  socket-proxy:
    image: tecnativa/docker-socket-proxy
    environment:
      - CONTAINERS=1
      - SERVICES=1
      - NETWORKS=1
      - EVENTS=1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks: [socket_proxy]
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

  traefik:
    image: traefik:v3
    network_mode: service:tailscale
    depends_on: [socket-proxy]
    command:
      - --api.dashboard=true
      - --providers.docker=true
      - --providers.docker.endpoint=tcp://socket-proxy:2375
      - --providers.docker.exposedbydefault=false
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
    volumes:
      - traefik_data:/data
    restart: unless-stopped

  dockhand:
    image: fnsys/dockhand:v1.0.0
    labels:
      - traefik.enable=true
      - traefik.http.routers.dockhand.rule=Host(`dockhand.homelab-gw.ts.net`)
      - traefik.http.routers.dockhand.entrypoints=websecure
      - traefik.http.routers.dockhand.tls=true
      - traefik.http.services.dockhand.loadbalancer.server.port=3000
    networks: [default]
    restart: unless-stopped
    volumes:
      - dockhand_data:/app/data

networks:
  socket_proxy:
    internal: true

volumes:
  tailscale_state:
  traefik_data:
  dockhand_data:

This works because Traefik "inherits" the Tailscale network via network_mode: service:tailscale, so ports 80/443 are reachable at the Tailscale address (MagicDNS) but not exposed publicly.

Using PostgreSQL database

Dockhand can also use PostgreSQL instead of the default SQLite:

docker run -d \
  --name dockhand \
  --restart unless-stopped \
  --user 0:0 \
  -p 3000:3000 \
  -e DATABASE_URL=postgres://user:password@postgres-host:5432/dockhand \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockhand_data:/app/data \
  fnsys/dockhand:v1.0.0

The database schema is created automatically on first run. Just ensure the database exists and the user has sufficient privileges.

Managing remote Docker hosts

Dockhand can manage Docker hosts beyond your local machine. There are several ways to connect to remote environments:

Hawser is a lightweight agent that enables secure remote Docker management without exposing the Docker API directly. It's especially useful for:

• Hosts behind NAT or firewalls (Edge mode - no inbound ports required)
• VPS or cloud instances with dynamic IPs
• Secure access without exposing Docker TCP port
• Homelab environments across different networks

See the Hawser section for detailed setup instructions.

System requirements

Dashboard

The dashboard provides a real-time overview of all your Docker environments. Each environment is displayed as a tile that can be resized and repositioned to suit your workflow.

Environment tiles

Each environment tile displays key information at a glance:

• Header - Environment name, icon, and connection status
• Container counts - Running, stopped, and total containers
• Resource metrics - CPU and memory usage with progress bars
• Health status - Warning banner for unhealthy or restarting containers
• Activity summary - Today's events and recent activity
• Top containers - Containers sorted by CPU usage (larger tiles)

Status indicators

Tiles display status icons in the header:

Tile sizing

Tiles can be resized to show more or less information. Drag the corner of any tile to resize it.

Layout management

The dashboard provides several ways to organize your tiles:

Auto-layout presets

Use the dropdown in the header to quickly apply preset layouts:

• Compact - All tiles at 1x1 size
• Standard - All tiles at 1x2 size
• Detailed - All tiles at 1x3 size
• Full - All tiles at 2x3 size

Drag and drop

Drag tiles by their header to reposition them. The layout is automatically saved to your browser's local storage.

Label filtering

If you've assigned labels to environments, you can filter the dashboard to show only environments with specific labels. Click the label pills at the top of the dashboard to toggle filtering.

Containers

The Containers page provides comprehensive management of all Docker containers across your environments.

List view

The container list displays all containers with sortable columns:

Search and sort

Use the search box to filter containers by name, image, or stack. Click column headers to sort. Press Esc to clear the search.

Bulk operations

Select multiple containers using the checkboxes, then use the bulk action buttons:

• Start - Start all selected stopped containers
• Stop - Stop all selected running containers
• Restart - Restart all selected containers
• Remove - Delete all selected containers

Container actions

Each container row has action buttons for common operations:

Creating containers

Click the Create container button to launch a new container. The modal provides all configuration options:

Basic settings

• Image - Select from local images or enter image:tag to pull
• Name - Container name (auto-generated if empty)
• Command - Override the default command
• Working directory - Set the working directory

Port mappings

Map container ports to host ports. Format: host_port:container_port/protocol

Volume mounts

Mount host directories or named volumes into the container:

• Bind mount - /host/path:/container/path
• Named volume - volume_name:/container/path
• Read-only - Append :ro for read-only access

Environment variables

Set environment variables as key-value pairs. Sensitive values are masked in the UI.

Network

Select the network mode:

• bridge (default) - Container gets its own IP on a bridge network
• host - Container shares the host's network stack
• none - No networking
• Custom network - Connect to a user-defined network

Restart policy

Resource limits

• CPU limit - Maximum CPU cores (e.g., 0.5 for half a core)
• Memory limit - Maximum memory (e.g., 512m, 1g)

Logs viewer

The logs viewer provides real-time streaming of container logs with ANSI color support.

Features

• Real-time streaming - Logs appear instantly via Server-Sent Events
• ANSI color rendering - Full color support for formatted output
• Pause/Resume - Toggle streaming to freeze the view
• Auto-scroll - Automatically scroll to the latest logs
• Download - Export logs as a text file
• Font size - Adjust between 10-18px

Connection status

The status indicator shows the current connection state:

• Live (green pulse) - Streaming active
• Connecting (yellow) - Establishing connection
• Disconnected (red) - Connection lost, will retry
• Paused (amber) - Streaming manually paused

Terminal

Open an interactive terminal session inside a running container.

Configuration

• Shell - Select bash, sh, zsh, or ash
• User - Run as root, nobody, or container default
• Font size - Adjust terminal font size

Keyboard shortcuts

• Cmd + L - Clear terminal
• Cmd + C - Copy selection
• Cmd + V - Paste

File browser

Browse and manage files inside running containers.

Features

• Navigation - Browse directories with breadcrumb trail
• Download - Download files or directories as tar archive
• Upload - Upload files to the container
• File info - View file sizes, types, and permissions

Auto-update

Configure automatic image updates for containers to keep them running the latest version.

Schedule options

• Daily - Update once per day at a specific time
• Weekly - Update on a specific day and time
• Custom - Use a cron expression for precise scheduling

Vulnerability criteria

When vulnerability scanning is enabled, you can block updates based on scan results:

Compose stacks

Manage Docker Compose stacks for multi-container applications. Dockhand supports both manually created stacks and stacks deployed from Git repositories.

Stack types

Creating stacks

Click Create stack to open the YAML editor:

1. Enter a stack name (becomes the Compose project name)
2. Write or paste your docker-compose.yml content
3. Optionally check "Deploy immediately" to start the stack
4. Click Create

Git integration

Deploy stacks directly from Git repositories with automatic synchronization.

Triggers: Scheduled auto-sync • Webhook from CI/CD • Manual deploy button

Configuration

• Repository - Select from configured Git repositories or add a new one
• Branch - Target branch to track
• Compose file path - Path to the compose file (default: docker-compose.yml)
• Auto-sync - Enable automatic sync on a schedule
• Schedule - Cron expression for auto-sync timing

Deployment behavior

Git stacks use intelligent deployment:

• Only redeploys when the Git commit changes (detected via git pull)
• Uses docker compose up -d --remove-orphans which only recreates changed services
• Manual "Deploy" button forces redeployment regardless of changes

Webhooks

Trigger stack deployments from external services like GitHub, GitLab, or CI/CD pipelines.

Push to repo → webhook triggers → Dockhand pulls changes → deploys updated stack

Webhook URL

Each Git stack gets a unique webhook URL:

https://your-dockhand.com/api/git/stacks/{id}/webhook

Supported methods

• GET - Simple trigger (for testing)
• POST - Standard webhook with optional signature verification

Webhook secret

For security, configure a webhook secret. The request signature is validated using HMAC-SHA256 in the X-Hub-Signature-256 header (GitHub compatible).

Images

The Images page shows all Docker images on the selected environment, grouped by repository.

Image actions

Pulling images

Click Pull image to download a new image:

1. Optionally select a registry (default: Docker Hub)
2. Enter the image name (e.g., nginx, redis)
3. Enter the tag (e.g., latest, alpine)
4. Click Pull

Progress is shown layer-by-layer with download percentages.

Vulnerability scanning

Dockhand integrates with Grype and Trivy vulnerability scanners to identify security issues in your images.

Severity levels

Export formats

Scan results can be exported in multiple formats:

• Markdown - Human-readable report
• CSV - Spreadsheet format for analysis
• JSON - Raw data for automation

Scan caching

Scan results are cached by image SHA256. Re-scanning the same image version returns cached results unless you force a fresh scan.

Registry operations

Pushing images

Push images to configured registries. Select the target registry and optionally specify a new tag.

Image history

View the layer-by-layer build history of an image, including:

• Layer size
• Creation timestamp
• Command that created the layer

Volumes

Manage Docker volumes for persistent data storage.

Volume actions

• Browse - Open volume browser (uses helper container)
• Clone - Create a copy of volume configuration
• Inspect - View detailed volume information
• Export - Download volume contents as tar archive
• Delete - Remove the volume (fails if in use)

Volume browser

Browse the contents of Docker volumes using a helper container.

Networks

Manage Docker networks for container communication.

Network drivers

Creating networks

Configure:

• Name - Network name
• Driver - Network driver type
• Subnet - CIDR notation (e.g., 172.20.0.0/16)
• Gateway - Gateway IP address
• Internal - Restrict external access
• Attachable - Allow manual container attachment

Connecting containers

Use the "Connect container" action to attach containers to a network with optional:

• Aliases - DNS aliases for the container on this network
• IPv4 address - Specific IP address assignment

Registry browser

Browse and search Docker registries to discover and pull images.

Features

• Search across configured registries
• View available tags for each image
• Pull images directly from search results
• View image details and manifests

Activity log

Track all Docker container events across your environments in real-time.

Event types

Filtering

Filter the activity log by:

• Container name - Text search
• Event type - Select specific event types
• Environment - Filter by environment
• Labels - Filter by environment labels
• Date range - Presets or custom range

Schedules

View and manage all scheduled jobs in one place.

Schedule types

Schedule management

• Enable/Disable - Toggle schedule without deleting
• Last run - When the schedule last executed
• Next run - Calculated next execution time
• Delete - Remove the schedule

System schedules

Dockhand includes built-in cleanup schedules that run automatically:

Configure retention periods in Settings > General > Cleanup jobs.

Hawser remote agent

Hawser is a lightweight Go agent that enables Dockhand to manage Docker hosts in various network configurations, including hosts behind NAT, firewalls, or with dynamic IPs.

Connection modes

Hawser supports two operational modes:

Installation

Quick install script

The recommended way to install Hawser on Linux:

curl -fsSL https://raw.githubusercontent.com/Finsys/hawser/main/scripts/install.sh | bash

This script:

• Detects OS and architecture (Linux amd64/arm64)
• Downloads the latest release from GitHub
• Installs to /usr/local/bin/hawser
• Creates config directory at /etc/hawser/
• Installs systemd service (or OpenRC on Alpine)

Docker installation

Standard mode:

docker run -d \
  --name hawser \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 2376:2376 \
  -e TOKEN=your-secret-token \
  ghcr.io/finsys/hawser:latest

Edge mode:

docker run -d \
  --name hawser \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e DOCKHAND_SERVER_URL=wss://your-dockhand.example.com/api/hawser/connect \
  -e TOKEN=your-agent-token \
  -e AGENT_NAME=my-server \
  ghcr.io/finsys/hawser:latest

Systemd service

Create /etc/systemd/system/hawser.service:

[Unit]
Description=Hawser - Remote Docker Agent for Dockhand
After=network-online.target docker.service
Wants=network-online.target
Requires=docker.service

[Service]
Type=simple
ExecStart=/usr/local/bin/hawser
Restart=always
RestartSec=10
EnvironmentFile=/etc/hawser/config

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now hawser

Configuration

Configure Hawser using environment variables or a config file at /etc/hawser/config:

Standard mode config

# Standard Mode Configuration
DOCKER_SOCKET=/var/run/docker.sock
PORT=2376
TOKEN=your-secret-token
AGENT_NAME=my-server
LOG_LEVEL=info

# Optional TLS
# TLS_CERT=/etc/hawser/server.crt
# TLS_KEY=/etc/hawser/server.key

Edge mode config

# Edge Mode Configuration
DOCKER_SOCKET=/var/run/docker.sock
DOCKHAND_SERVER_URL=wss://your-dockhand.example.com/api/hawser/connect
TOKEN=your-agent-token-from-dockhand
AGENT_NAME=my-server
LOG_LEVEL=info

# Connection settings
HEARTBEAT_INTERVAL=30
RECONNECT_DELAY=1
MAX_RECONNECT_DELAY=60

Environment variables reference

TLS configuration

TLS certificate handling differs based on which side initiates the connection:

Standard mode TLS

When Hawser uses a self-signed TLS certificate, configure the CA certificate in Dockhand:

1. Go to Settings > Environments
2. Edit the Hawser Standard environment
3. Set protocol to HTTPS
4. Paste the CA certificate in the CA certificate field
5. Optionally enable Skip TLS verification for testing (insecure)

Edge mode TLS

When Dockhand uses a self-signed TLS certificate, configure the CA certificate on the Hawser agent:

# Edge mode with self-signed Dockhand certificate
DOCKHAND_SERVER_URL=wss://your-dockhand.example.com/api/hawser/connect
TOKEN=your-agent-token
CA_CERT=/etc/hawser/dockhand-ca.pem

# Or skip verification (insecure, for testing only)
# TLS_SKIP_VERIFY=true

Token management

Edge mode requires tokens generated in Dockhand:

1. Go to Settings > Environments
2. Create or edit an environment with "Hawser - Edge" connection type
3. Click Generate Token
4. Copy the token immediately (shown only once)
5. Configure Hawser on your Docker host with this token

Troubleshooting

Common issues

Debug mode

Enable detailed logging:

LOG_LEVEL=debug hawser

Check logs

# Systemd
sudo journalctl -u hawser -f

# Docker
docker logs -f hawser

Settings

Configure Dockhand behavior, environments, authentication, and integrations.

General settings

Vulnerability scanner defaults

Configure default CLI arguments for vulnerability scanners. These settings allow you to adjust scanner behavior if Trivy or Grype CLI options change in future versions, or to add custom flags for your environment:

• Grype CLI args - Default: -o json -v {image}
• Trivy CLI args - Default: image --format json {image}

The {image} placeholder is replaced with the actual image name at scan time.

Cleanup jobs

Configure automatic cleanup of old data to prevent database growth:

Each cleanup job can be enabled/disabled independently with configurable retention periods (1-365 days). Jobs run automatically on a daily schedule.

Environments

Manage Docker environment connections.

Connection types

Environment options

• Name - Display name for the environment
• Icon - Custom icon from icon library
• Labels - Tags for filtering (with colors)
• Default environment - Selected by default on page load
• Collect metrics - Enable CPU/memory monitoring
• Collect activity - Track container events
• Highlight changes - Visual indicators for stat changes

Vulnerability scanning

Per-environment scanner configuration:

• Scanner - None, Grype, Trivy, or Both
• Scan on pull - Auto-scan pulled images
• Custom CLI args - Override default scanner arguments

Registries

Configure Docker registries for image operations.

• Name - Display name
• URL - Registry endpoint
• Username/Password - Authentication credentials
• Default - Set as default for pull operations

Git

Manage Git credentials and repositories for stack deployment.

Credentials

• SSH keys - For SSH authentication
• HTTPS credentials - Username/password or token

Repositories

• URL - Git repository URL
• Branch - Default branch to track
• Credential - Link to saved credential

Config sets

Config sets are reusable configuration templates that can be applied when creating containers. They help maintain consistency and save time when deploying multiple containers with similar configurations.

What's included in a config set

• Environment variables - Predefined key-value pairs
• Labels - Container labels for organization and filtering
• Port mappings - Common port configurations
• Volume mounts - Standard volume configurations
• Network mode - Network settings (bridge, host, etc.)
• Restart policy - Container restart behavior

Using config sets

1. Go to Settings > Config sets
2. Click Add config set
3. Enter a name and configure the desired options
4. Save the config set
5. When creating a new container, select the config set from the dropdown to pre-fill values

Notifications

Configure notification channels for alerts.

Channel types

• SMTP - Email notifications via SMTP server
• Apprise - Webhooks for Discord, Slack, Telegram, ntfy, Gotify, Pushover, etc.

Event types

Configure which events trigger notifications:

• Container events - start, stop, unhealthy, OOM
• Auto-update events - success, failed, blocked
• Git stack events - sync success, failed, skipped
• Stack events - deployed, failed
• Security events - vulnerabilities found
• System events - environment offline, disk warning

Authentication

Configure user authentication and access control.

General settings

• Enable authentication - Toggle auth for the application
• Session timeout - Session expiration (1-7 days)

Local users

Create and manage local user accounts:

• Username, display name, email
• Password (Argon2id hashed)
• Admin role toggle
• Avatar upload
• Enable/disable account

OIDC/SSO

Configure Single Sign-On with OpenID Connect providers.

Supported providers

• Google
• Microsoft Azure AD
• Okta
• Keycloak
• Auth0
• Any OIDC-compliant provider

Configuration

• Name - Provider display name
• Issuer URL - OIDC discovery endpoint
• Client ID - OAuth client ID
• Client secret - OAuth client secret
• Scopes - OAuth scopes (default: openid profile email)

LDAP/Active Directory Enterprise

Connect to LDAP or Active Directory for user authentication.

Connection settings

• Server URL - LDAP server (e.g., ldap://ldap.example.com:389)
• Bind DN - Service account DN for searching
• Bind password - Service account password
• Base DN - Search base (e.g., dc=example,dc=com)

User search

• User filter - LDAP filter template
  • OpenLDAP: (uid={{username}})
  • Active Directory: (sAMAccountName={{username}})
• Username attribute - Attribute for username (uid, sAMAccountName)
• Email attribute - Attribute for email (mail)
• Display name attribute - Attribute for display name (cn)

Group settings

• Group base DN - Where to search for groups
• Admin group - Group DN for admin access
• Member filter - Filter to find user's groups

TLS settings

• Enable TLS - Use LDAPS or StartTLS
• CA certificate - Custom CA for verification

Roles (RBAC) Enterprise

Configure role-based access control for granular permissions.

System roles

• Admin - Full access to everything
• Operator - Manage containers, images, stacks
• Viewer - Read-only access

Custom roles

Create roles with granular permissions:

• Containers - view, create, edit, start/stop, remove, exec, logs
• Images - view, pull, remove
• Volumes - view, create, remove, browse
• Networks - view, create, remove
• Stacks - view, create, edit, deploy, remove
• And more...

Environment scoping

Custom roles can be scoped to specific environments:

• All environments - Role applies everywhere
• Specific environments - Role only applies to selected environments

License

Activate and manage your Enterprise license.

Enterprise features

An Enterprise license unlocks:

• Role-based access control (RBAC)
• LDAP/Active Directory integration
• Audit logging
• Priority support

Activation

1. Enter your license name (customer name)
2. Enter your license key
3. Click Activate

The license is validated against:

• Customer name
• Hostname (or wildcard)
• Expiration date
• Cryptographic signature

Enterprise features

Enterprise edition adds advanced security and compliance features for organizations.

Role-based access control

RBAC provides fine-grained control over who can access what:

• Users can be assigned multiple roles
• Roles define permissions for resources and actions
• Environment scoping limits role access to specific environments

Free vs Enterprise

Audit logging

Track all user actions for compliance and security auditing.

Audit logs capture:

• Who performed the action (user)
• What action was performed (create, update, delete, start, stop, etc.)
• What resource was affected (container, image, stack, etc.)
• When the action occurred (timestamp)
• Additional context (IP address, user agent)

Multi-factor authentication

Add an extra layer of security with TOTP-based MFA. This feature is available in both free and enterprise edition.

Setup process

1. Go to your Profile page
2. Click Enable MFA
3. Scan the QR code with an authenticator app (Google Authenticator, Authy, etc.)
4. Enter the verification code
5. Save your backup codes securely

Keyboard shortcuts

Global

Terminal

Troubleshooting

Dockhand won't start

• Check Docker socket is accessible: docker ps
• Verify port 5173 is not in use
• Check container logs: docker logs dockhand

Can't connect to environment

• Verify Docker is running on the target host
• Check firewall rules allow connection
• For Hawser: verify agent is running and token is correct

Locked out of authentication

Use emergency scripts to regain access:

Emergency scripts

Recovery scripts are located in /app/scripts/emergency/ inside the container:

# Disable authentication
docker exec -it dockhand /app/scripts/emergency/disable-auth.sh

# Create admin user (admin/admin123)
docker exec -it dockhand /app/scripts/emergency/create-admin.sh

# Reset a user's password
docker exec -it dockhand /app/scripts/emergency/reset-password.sh username NewPassword123

# List all users
docker exec -it dockhand /app/scripts/emergency/list-users.sh

# Clear all sessions (force re-login)
docker exec -it dockhand /app/scripts/emergency/clear-sessions.sh

# Backup database
docker exec -it dockhand /app/scripts/emergency/backup-db.sh /app/data/backups

API reference

Dockhand exposes a REST API that can be used for automation and integration with other tools. All endpoints are available at /api/.

Containers

Stacks

Images

Volumes & Networks

Other endpoints

Query parameters

Most endpoints accept an env query parameter to specify the target environment:

GET /api/containers?env=1
GET /api/images?env=2

Example: Using curl

# List containers
curl -s http://localhost:3000/api/containers | jq

# Restart a container
curl -X POST http://localhost:3000/api/containers/abc123/restart

# Pull an image
curl -X POST http://localhost:3000/api/images/pull \
  -H "Content-Type: application/json" \
  -d '{"image": "nginx:latest"}'

# Create a stack
curl -X POST http://localhost:3000/api/stacks \
  -H "Content-Type: application/json" \
  -d '{"name": "mystack", "compose": "version: \"3\"\\nservices:\\n  web:\\n    image: nginx"}'

Appendix: OIDC/SSO configuration guide

This guide explains how to configure OpenID Connect (OIDC) Single Sign-On in Dockhand.

Overview

Dockhand supports OIDC authentication, allowing users to log in using external identity providers:

• Google
• Microsoft Azure AD
• Okta
• Keycloak
• Auth0
• Any OIDC-compliant provider

Keycloak setup example

1. Create a realm

1. Log in to Keycloak Admin Console
2. Create a new realm (e.g., dockhand)

2. Create a client

1. Go to Clients > Create client
2. Configure:
   • Client ID: dockhand-app
   • Client type: OpenID Connect
   • Client authentication: ON (for confidential client)
3. Click Next and configure:
   • Valid redirect URIs: https://your-domain/api/auth/oidc/callback
   • Web origins: https://your-domain
4. Click Save
5. Go to Credentials tab and copy the Client secret

3. Configure group mapper

To pass group membership to Dockhand for role mapping:

1. Go to Clients > dockhand-app > Client scopes
2. Click on dockhand-app-dedicated scope
3. Click Add mapper > By configuration > Group Membership
4. Configure:
   • Name: groups
   • Token Claim Name: groups
   • Full group path: OFF
   • Add to ID token: ON
   • Add to access token: ON
   • Add to userinfo: ON
5. Click Save

4. Create groups

Create groups in Keycloak that map to Dockhand roles:

1. Go to Groups > Create group
2. Create groups such as:
   • dockhand-admins - for administrator access
   • dockhand-operators - for operator access
   • dockhand-viewers - for read-only access

5. Assign users to groups

1. Go to Users > [select user] > Groups
2. Click Join Group
3. Select the appropriate group(s)

Dockhand configuration

1. Enable Enterprise license

Role mapping features require an Enterprise license:

1. Go to Settings > License
2. Enter your license name and key
3. Click Activate

2. Configure OIDC provider

1. Go to Settings > Auth > SSO
2. Click Add provider
3. Fill in the basic settings:

3. Configure claim mappings (optional)

4. Configure admin mapping

Grant admin access based on group membership:

1. Edit the OIDC provider
2. Scroll to Groups/roles claim section
3. Configure:
   • Claim name: groups
   • Admin value(s): dockhand-admins

Users with dockhand-admins in their groups claim will automatically receive Admin role.

5. Configure role mappings (Enterprise)

Map additional groups to Dockhand roles:

1. Edit the OIDC provider
2. Scroll to Claim to role mappings section
3. Click Add mapping
4. For each mapping, configure:
   • Claim name: groups
   • Claim value: e.g., dockhand-operators
   • Role: Select from dropdown

Other identity providers

Google

Issuer URL: https://accounts.google.com
Scopes: openid profile email

Note: Google doesn't support custom claims for role mapping. All Google users will need manual role assignment.

Azure AD

Issuer URL: https://login.microsoftonline.com/{tenant-id}/v2.0
Scopes: openid profile email

For role mapping, configure Azure AD to include group claims in the token.

Okta

Issuer URL: https://{your-domain}.okta.com
Scopes: openid profile email groups

Configure a groups claim in the Authorization Server.

Troubleshooting OIDC

User has no permissions after login

• Verify the user is assigned to groups in your IdP
• Check that the groups mapper is configured correctly
• Ensure Add to ID token is enabled for the groups mapper
• Verify the claim name matches in Dockhand config (case-sensitive)

Admin mapping not working

• Verify the admin claim name matches exactly (case-sensitive)
• Check that the admin value matches the group name exactly
• Ensure the user is a member of the admin group in your IdP

Redirect URI mismatch error

• Ensure the redirect URI in Dockhand matches exactly what's configured in your IdP
• Check for trailing slashes
• Verify the protocol (http vs https) matches

Token claims not appearing

For Keycloak:

1. Go to Clients > [client] > Client scopes
2. Verify mappers are configured
3. Use Keycloak's Evaluate feature to test token contents:
   • Go to Clients > [client] > Client scopes > Evaluate
   • Select a user and click Generated ID token
   • Verify the groups claim is present

Appendix: LDAP/Active Directory configuration guide

This guide explains how to configure LDAP or Active Directory authentication in Dockhand.

Supported directories

• OpenLDAP
• Microsoft Active Directory
• FreeIPA
• 389 Directory Server
• Any LDAP v3 compliant directory

How LDAP authentication works

1. User enters username and password in Dockhand
2. Dockhand connects to LDAP server using bind credentials (service account)
3. Searches for the user entry using the configured filter
4. Attempts to bind as the found user with the provided password
5. If successful, retrieves user attributes (email, display name)
6. Optionally checks group membership for admin/role assignment
7. Creates or updates user in Dockhand and establishes session

Key terminology

OpenLDAP configuration

Example directory structure

dc=example,dc=com
├── ou=users
│   ├── uid=john (cn=John Doe, mail=john@example.com)
│   └── uid=jane (cn=Jane Smith, mail=jane@example.com)
└── ou=groups
    ├── cn=dockhand-admins (member: uid=john,ou=users,dc=example,dc=com)
    └── cn=dockhand-users (member: uid=jane,ou=users,dc=example,dc=com)

Dockhand configuration for OpenLDAP

Active Directory configuration

Example AD structure

DC=corp,DC=example,DC=com
├── OU=Users
│   ├── CN=John Doe (sAMAccountName=jdoe, mail=jdoe@example.com)
│   └── CN=Jane Smith (sAMAccountName=jsmith, mail=jsmith@example.com)
└── OU=Groups
    ├── CN=Dockhand Admins
    └── CN=Dockhand Users

Dockhand configuration for Active Directory

Alternative AD user filters

# By sAMAccountName (most common)
(sAMAccountName={{username}})

# By userPrincipalName (email-style login)
(userPrincipalName={{username}})

# By both (allow either format)
(|(sAMAccountName={{username}})(userPrincipalName={{username}}))

# Only enabled accounts
(&(sAMAccountName={{username}})(!(userAccountControl:1.2.840.113556.1.4.803:=2)))

Group membership filters

# OpenLDAP with groupOfNames
(&(objectClass=groupOfNames)(member={{user_dn}}))

# OpenLDAP with posixGroup
(&(objectClass=posixGroup)(memberUid={{username}}))

# Active Directory
(&(objectClass=group)(member={{user_dn}}))

The {{user_dn}} placeholder is replaced with the user's full DN.

Role mappings (Enterprise)

Map LDAP groups to Dockhand roles:

1. Click Add mapping
2. Enter the full group DN
3. Select the Dockhand role

TLS/SSL configuration

Server URL formats:

• ldap://hostname:389 - Plain LDAP (port 389)
• ldaps://hostname:636 - LDAP over SSL (port 636)
• ldap://hostname:389 with TLS enabled - StartTLS

For self-signed certificates, add the CA certificate in TLS settings.

Troubleshooting LDAP

Connection refused

• Verify LDAP server is running and accessible
• Check firewall rules (ports 389/636)
• Test connectivity: telnet ldap.example.com 389

Invalid credentials (Bind DN)

• Verify Bind DN is correct and complete
• Check password is correct
• Ensure service account is not locked/disabled

User not found

• Verify Base DN includes the user's location
• Test user filter manually with ldapsearch:

# OpenLDAP
ldapsearch -x -H ldap://localhost:389 \
  -D "cn=admin,dc=example,dc=com" \
  -W \
  -b "ou=users,dc=example,dc=com" \
  "(uid=john)"

# Active Directory
ldapsearch -x -H ldap://dc01.corp.example.com:389 \
  -D "CN=Service Account,DC=corp,DC=example,DC=com" \
  -W \
  -b "DC=corp,DC=example,DC=com" \
  "(sAMAccountName=jdoe)"

User logs in but has no permissions

• Verify user is member of appropriate LDAP group
• Check group DN matches exactly (case-sensitive)
• Verify member filter is correct for your directory type
• Ensure role mappings are configured

TLS/SSL certificate errors

• For self-signed certificates, add the CA certificate in TLS settings
• Verify server hostname matches certificate CN/SAN
• Check certificate is not expired