a2coder/docklite repository overview

⁠DockLite

A lightweight, Docker-Desktop-style web GUI for managing Docker containers. View containers grouped by Compose project, start/stop containers or whole projects, and tail live logs — all from one page.

No database. A single admin login is configured entirely through environment variables.

⁠Quickstart

1. Create a docker-compose.yml file and paste the below content:

services:
  docklite:
    image: a2coder/docklite:latest
    # build: .   # uncomment to build locally instead of pulling
    ports:
      - "3000:3000"
    environment:
      AUTH_USERNAME: ${AUTH_USERNAME}
      AUTH_PASSWORD_HASH: ${AUTH_PASSWORD_HASH}
      SESSION_SECRET: ${SESSION_SECRET}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped

1. Start the compose project by running docker compose up from the directory containing the yaml file.

⁠Environment variables

⁠Updating containers

Each container row has an update button (⟳) that pulls the container's image tag again and recreates the container from its existing configuration (name, env, labels, volumes, networks, restart policy) with the new image. Compose projects get an Update all button that does this for every container in the project. docklite talks to Docker only through the socket, so no compose files or docker CLI are required inside the container.

⁠CI Webhook

Set WEBHOOK_API_KEY to enable two POST endpoints that trigger the same update from CI. Authenticate with Authorization: Bearer <WEBHOOK_API_KEY>:

# Update one container (by name or id)
curl -fsSL -X POST \
  -H "Authorization: Bearer $WEBHOOK_API_KEY" \
  https://docklite.example.com/api/webhook/container/my-service

# Update every container in a Compose project
curl -fsSL -X POST \
  -H "Authorization: Bearer $WEBHOOK_API_KEY" \
  https://docklite.example.com/api/webhook/project/my-project

Responses are JSON: {"ok":true,...} on success, {"ok":false,"error":...} with status 401 (bad token), 503 (webhook disabled), or 500 (update failed). To pull from a private registry, see Private registries below.

⁠Private registries

DockLite picks credentials per pull, based on the registry the image comes from. Configure any number of them in a YAML file:

# registries.yml
registries:
  - host: ghcr.io
    username: acme-ci
    password_b64: Z2hwX3h4eHh4eHh4eHh4eA==

  - host: registry.internal.acme.com:5000
    username: deploy
    password_b64: c3VwZXItc2VjcmV0

  - host: docker.io
    username: acmebot
    password_b64: ZGNrcl9wYXRfeHl6

Encode each password with printf %s 'your-token' | base64 — password_b64 is base64, not encryption; it just stops a token being read over your shoulder. Keep the file chmod 600 and out of version control.

Mount the file and point DockLite at it — both steps are required:

    environment:
      REGISTRY_CONFIG_PATH: /config/registries.yml
    volumes:
      - ./registries.yml:/config/registries.yml:ro

The host is matched against the image reference (ghcr.io/acme/api → ghcr.io; bare names and acme/api-style references → docker.io). An image from a registry with no entry pulls anonymously; a broken config file fails the pull loudly instead. Edits take effect on the next pull, no restart needed.

The single-pair REGISTRY_AUTH_USER/REGISTRY_AUTH_PASSWORD variables still work as a fallback and are ignored once REGISTRY_CONFIG_PATH is set.

⁠Security notes

• There is no login rate limiting or lockout. This app is meant for a private network, VPN, or behind a reverse proxy with its own access controls — do not expose it directly to the public internet.
• The session cookie is httpOnly, SameSite=Lax, and marked Secure automatically when NODE_ENV=production.
• Every server action and API route re-checks the session independently; proxy.ts is a convenience gate, not the only auth check.