DockGo

A lightweight, secure Docker update agent — single binary, no fuss.

What is DockGo?

DockGo is a simple, single-binary application that monitors your Docker containers for updates. It focuses on visibility and control rather than automatic unattended updates and it provides:

1. A Web Dashboard to see container status and available updates at a glance.
2. A CLI for scripting and manual checks.
3. Smart Updates that handle standard containers, private registries, and Docker Compose services.

Why DockGo?

Most Docker update tools (like Watchtower or Ouroboros) are great, but can be:

• Heavy: Running complex logical loops or requiring root.
• Insecure: Often demanding full root access to the socket without dropping privileges or providing authentication.
• Opaque: Updating things silently without a clear UI to see what is happening.

DockGo is different:

• Security-focused by default: Runs as a non-root user (dockgo).
• Transparent: You decide when to update (via UI or CLI), or automate it with scripts.
• Lightweight: Written in Go, typically very low memory footprint (~10–30MB).

---

Quick Start

The fastest way to run DockGo is via Docker:

docker run -d \
  --name dockgo \
  -p 3131:3131 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e AUTH_USERNAME=admin \
  -e AUTH_PASSWORD=changeme \
  ghcr.io/jisevind/dockgo:latest

Visit http://localhost:3131 to see your dashboard!

---

Security Model

DockGo takes security seriously.

1. Non-Root Execution: Inside the container, the process runs as the dockgo user (UID 1000), not root.
2. Socket Permissions: The entrypoint script creates a docker group matching the host's socket GID, allowing the dockgo user to talk to the engine without being root.
3. Authentication:
   • User Login: Set AUTH_USERNAME and map either AUTH_PASSWORD_HASH (recommended) or AUTH_PASSWORD (convenience/testing) to enable a secure login flow with HttpOnly cookies.
     • Generate hashes using the built-in CLI command, e.g., dockgo hash-password secret.
   • Legacy Token: Set API_TOKEN for simple script integrations.
   • CORS: Disabled by default. Only enabled if you specifically set CORS_ORIGIN.
4. Compose Path Restrictions: The ALLOWED_COMPOSE_PATHS environment variable lets you restrict which Docker Compose working directories can be updated. This is a defense-in-depth measure to prevent accidental or malicious updates outside your intended container environments. The restriction applies to both native Compose updates and fallback to standalone API recreation for Compose-managed containers. Note: This restriction only applies to updates, not discovery—DockGo will still discover and monitor all containers on your system, but will only allow updating those whose compose files are within the allowed paths.
5. Log Redaction: Sensitive errors and login failures are redacted in logs.
6. Hardened SSE Streams: All real-time progress events are strictly JSON-marshaled and HTML-escaped to prevent XSS and stream-breaking injections.
7. Deep RNG Validation: Fail-fast architecture that terminates the application immediately if the host operating system's entropy pool (crypto/rand) fails to provide secure random bytes.
8. Strict Credential Omission: Sensitive fields (passwords/tokens) are cryptographically tagged to be omitted from all JSON serialization at the compiler level.

[!CAUTION] CRITICAL SECURITY WARNING: Docker Socket Exposure

Mounting /var/run/docker.sock explicitly grants full root-level access to your host machine. This is an unavoidable requirement for any tool that manages Docker containers, but it comes with severe security implications.

You MUST:

1. Never expose DockGo publicly to the internet without robust authentication.
2. Use Network Isolation: Run DockGo on a trusted, private local network.
3. Implement a Reverse Proxy: If you must expose it, place it behind a secure reverse proxy (like Nginx, Traefik, or Caddy) equipped with SSL/TLS and preferably external Single Sign-On (SSO) or robust reverse-proxy-level authentication, in addition to DockGo's built-in authentication.

Failing to secure this endpoint is effectively equivalent to giving an attacker root-level control over the host.

---

Features

• Web Dashboard: Real-time status, "Update" buttons, and progress tracking.
• Server Stats: Live CPU, RAM, and disk usage of the selected host in the dashboard header.
• Container Actions: Start, stop, and restart directly from the UI.
• Real-time Logs: View container logs with ANSI color support inline seamlessly.
• Smart Discovery:
  • Checks standard Docker Hub images.
  • Supports Private Registries (using your host's credentials).
  • Works for most standard Docker Compose setups.
• Apprise Notifications: Sends instant automated alerts for newly discovered updates and container upgrade status to over 100+ supported services (Discord, Slack, Telegram, Gotify, etc.).
• Autonomous Scheduler: Periodically checks for container updates in the background without needing the UI open (default: 24h).
• Safe Mode: Use --safe to pull images without restarting running containers (CLI only).
• Network Preservation: Keeps static IPs and MAC addresses when recreating containers.
• Registry Caching: Caches registry digests for 10 minutes to prevent rate-limiting.
• Log Level Control: adjustable verbosity via LOG_LEVEL.

---

Configuration

Configure DockGo using environment variables:

---

Multi-Host Management (Agents)

DockGo can manage containers and Compose stacks on multiple remote hosts from one dashboard. A lightweight agent runs on each managed host, dials out to the server over a secure WebSocket channel, and the server relays the dashboard operations to it. No inbound ports are required on agent hosts.

• Create agents on the dashboard's Agents view; the server returns a one-time key (AGENT_KEY) for the remote host.
• Use the host selector in the dashboard header to switch between the local host and each agent.
• Containers, stats, scans, updates, logs, and stacks all operate on the selected host.
• Run the agent with the ghcr.io/jisevind/dockgo:agent-latest image (bundles the Docker CLI and Compose plugin).
• Git-kind stacks are not supported on remote agents.

The agent is deployed separately from the server: one docker-compose.agent.yml.example per managed host, never co-located with the DockGo server compose file. You only need an agent on hosts whose Docker daemon you cannot (or do not want to) give the DockGo server direct socket access to.

See Multi-Host Management with DockGo Agents for full setup, security, and key-rotation instructions.

---

Documentation

Start with the new user documentation:

• Documentation Index
• Quickstart
• Installation
• Configuration
• Dashboard and Updates
• Stacks
• Multi-Host Management (Agents)
• Notifications
• Backup and Restore
• Troubleshooting
• Internals

Additional reference material:

• Notifications covers the Apprise integration and example targets.
• Configuration covers API Token authentication.
• Internals covers the GitHub Actions release flow and the registered-stacks design.

Example docker-compose.yml:

services:
  dockgo:
    image: ghcr.io/jisevind/dockgo:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "3131:3131"
    environment:
      - LOG_LEVEL=info
      - AUTH_USERNAME=admin
      # Generate with: dockgo hash-password your_password
      - AUTH_PASSWORD_HASH=$$2a$$10$$YOUR_GENERATED_HASH_HERE
      # Optional: Restrict updates to specific Compose directories
      - ALLOWED_COMPOSE_PATHS=/opt/docker,/srv/compose
      # Optional: Map host paths when DockGo sees Compose projects at a
      # different path than the Docker host (common on Windows).
      # - COMPOSE_PATH_MAPPING=D:\Docker:/compose

Compose Stacks: Linux vs Windows

If you want reliable Compose stack updates from the DockGo container, the mount layout matters.

Linux: prefer same-path mounts and Host Native

On Linux, the recommended setup is to mount the Compose root into DockGo at the exact same absolute path as the host:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock
  - ./data:/app/data
  - /home/johan/docker:/home/johan/docker

With that setup:

• do not set COMPOSE_PATH_MAPPING
• register Linux stacks as Host Native

This is the most reliable option because DockGo and the Docker host resolve paths the same way, including relative bind mounts like ./app_data.

Windows, or any different mount path: use Mapped

If DockGo sees the Compose project at a different path than the host, use a path mapping instead. This is the normal setup on Windows with a Linux DockGo container:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock
  - ./data:/app/data
  - D:\Docker:/compose

COMPOSE_PATH_MAPPING=D:\Docker:/compose

With that setup:

• register those stacks as Mapped
• keep the canonical stack paths as host paths like D:\Docker\bazarr

You can also use Mapped on Linux if you deliberately mount the Compose root to a different internal path such as /compose, but Host Native is preferred on Linux whenever possible.

---

CLI Usage

You can use the dockgo binary directly for scripting or manual checks.

# Check all containers
dockgo check

# Check with JSON output (great for scripts)
dockgo check -json

# Generate a password hash for the dashboard server configuration
dockgo hash-password supersecretpassword
dockgo check -json

# Update a specific container
dockgo update -y my-container

# Update ALL containers
dockgo update -a

# Safe Mode: Pull only, don't restart running containers
dockgo update -safe -a

# Force Mode: Restart even if running
dockgo update -force -y my-container

# Typical workflow:
dockgo check
dockgo update -a

Flags

• -y <name>: Target specific container.
• -a: Target all containers with updates.
• -json: Output standard JSON.
• -stream: Output SSE-compatible line-delimited JSON.
• -preserve-network: Preserve network settings (IP/MAC) during recreation.

---

Building from Source

git clone https://github.com/Jisevind/dockgo.git
cd dockgo
go build -o dockgo ./cmd/dockgo

Building for Windows

If you want to run the DockGo binary natively on Windows (e.g. as a background service or CLI tool), you can build the .exe directly:

git clone https://github.com/Jisevind/dockgo.git
cd dockgo
$env:GOOS="windows"
$env:GOARCH="amd64"
go build -o dockgo.exe ./cmd/dockgo

Troubleshooting

Windows Connection Issues

If you see an error like failed to connect to Docker, ensure Docker Desktop is running. You may need to set the DOCKER_HOST environment variable if the default connection fails:

$env:DOCKER_HOST = "npipe:////./pipe/docker_engine"

Docker Container "no such file or directory"

If the container crashes with exec ./entrypoint.sh: no such file or directory, it likely has Windows line endings (CRLF). Ensure entrypoint.sh uses Unix line endings (LF). The build process should handle this, but if you are mounting the file locally, you may need to convert it.