Skip to content

Docker Registry

Watchgrid includes a built-in private Docker registry for storing and distributing container images across your fleet.

Overview

The registry runs as a registry:2 container alongside the Watchgrid server. It's accessible:

  • From the server host: localhost:5000
  • From any VPN-connected device: registry.wg:5000 (via Magic DNS)

Pushing Images

Tag your images with the registry address and push:

# Build your image
docker build -t myapp:latest .

# Tag for the Watchgrid registry
docker tag myapp:latest registry.wg:5000/myapp:latest

# Push
docker push registry.wg:5000/myapp:latest

Before a device has joined the VPN, use localhost:5000 instead of registry.wg:5000.

Pulling Images

From any device on the VPN:

docker pull registry.wg:5000/myapp:latest

K3s devices pull from the registry automatically when image names start with registry.wg:5000/.

Web UI

The registry is browsable through the Watchgrid dashboard:

  1. Go to System → Registry
  2. The page shows:
  3. Registry status — online/offline indicator
  4. Total image count
  5. Image list — repository names, tags, and sizes
  6. Actions per image:
  7. Copy the pull command
  8. Delete a specific tag
  9. Click Push Instructions for a quick reference on how to tag and push

Tenant Filtering

Toggle Show all tenants to see images from all tenants, or filter to only the current tenant's images (images prefixed with the tenant ID).

Authentication

Registry authentication is optional. When enabled:

Variable Description
REGISTRY_USERNAME Registry login username
REGISTRY_PASSWORD Registry login password

Set these environment variables in your docker-compose.yml to require authentication for push/pull operations.

Push Notifications (update detection)

Pushing a new image is how you ship app updates: deployments that reference a repo:tag show Update available in the App Store's Deployments tab as soon as the digest behind that tag changes — see Applications → Updates, Upgrades & Rollback.

Detection works out of the box via polling (default every 60s, tunable with WATCHGRID_REGISTRY_POLL_SECONDS on the server). For instant detection, enable the registry's native notifications webhook:

  1. Set a shared secret on the server container: 
    environment:
  - WATCHGRID_REGISTRY_EVENTS_TOKEN=<random-secret>
  2. Configure the registry container to post events to the server: 
    environment:
  - |
    REGISTRY_NOTIFICATIONS_ENDPOINTS=
    - name: watchgrid
      url: http://server:8080/api/registry/events
      headers:
        Authorization: [Bearer <random-secret>]
      timeout: 3s
      threshold: 5
      backoff: 10s

The webhook endpoint returns 404 while WATCHGRID_REGISTRY_EVENTS_TOKEN is unset, so leaving it unconfigured is safe — polling keeps working regardless.

Garbage Collection

The registry doesn't automatically clean up deleted image layers. To reclaim disk space:

docker exec registry bin/registry garbage-collect /etc/docker/registry/config.yml

Run this periodically or after deleting many images.