Self-Update

Drydock can gracefully update itself when a new version is available, using a safe rollback-capable process that ensures zero downtime.

How it works

Drydock detects when its own container image has an update available, just like any other monitored container. When the Docker trigger runs for the drydock container, it uses a special self-update flow that ensures zero downtime and safe rollback.

Requirements

• The Docker socket must be bind-mounted at /var/run/docker.sock
• The Docker trigger must be enabled
• Drydock must be able to create temporary helper containers

Update sequence

1. Notify UI — A dd:self-update SSE event is broadcast to all connected browsers, displaying an animated full-screen overlay. The server waits for at least one browser to acknowledge receipt before proceeding (see SSE acknowledgment below)
2. Backup current image — The running image is backed up before proceeding
3. Pull new image — The updated image is pulled while the current container is still running
4. Rename old container — The current container is renamed to drydock-old-{timestamp} to free the original name
5. Create new container — A new container is created with the original name and updated image (not started yet)
6. Helper container — A temporary container is spawned with the Docker socket mounted. It:
   • Stops the old container
   • Starts the new container
   • Deletes the old container on success
   • If the new container fails to start, restarts the old container as a fallback
7. Reconnect — The UI automatically reconnects to the new container

Error recovery

If any step fails, drydock attempts to restore the previous state:

• If new container creation fails, the old container is renamed back to its original name
• If the helper container fails to spawn, the new container is removed and the old container is renamed back
• If the new container fails to start, the helper restarts the old container

SSE acknowledgment

When the self-update begins, the server needs to ensure that connected browsers have received the update notification and displayed the overlay before the container is replaced. This is handled by an ack flow:

1. Each SSE client receives a clientId and clientToken when it connects to the /api/events/ui endpoint (via a dd:connected event).
2. When the dd:self-update event is broadcast, the server records which client tokens were connected at that moment.
3. Browsers acknowledge the event by sending POST /api/events/ui/self-update/:operationId/ack with their clientId and clientToken.
4. Once at least one acknowledgment is received (or the timeout expires), the update proceeds.

The ack timeout defaults to 3 seconds. If no browsers are connected, the update proceeds immediately without waiting.

Dry-run mode

When DD_TRIGGER_DOCKER_{trigger_name}_DRYRUN=true, the self-update is logged but not executed. The new image is pulled ahead of time but no container replacement occurs.

Example

services:
  drydock:
    image: codeswhat/drydock:latest
    container_name: drydock
    labels:
      - dd.watch=true
    environment:
      - DD_TRIGGER_DOCKER_LOCAL_PRUNE=true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - drydock-data:/store
    ports:
      - "3000:3000"

volumes:
  drydock-data: