tiny-forge/PLAN.md

Docker Watcher — Implementation Plan

Overview

A self-hosted tool that automates Docker container deployment with Nginx Proxy Manager integration. Detects new images from Gitea/GitHub registries, deploys containers, and configures reverse proxy routing — all from a web dashboard.

Architecture

Gitea CI → pushes image → Registry
                              ↓
                    Docker Watcher (Go)
                    ├── Webhook listener (instant)
                    └── Registry poller (fallback)
                              ↓
                    Match tag → project + stage
                              ↓
              ┌── auto_deploy? ──┐
              ↓                   ↓
        Deploy now          Notify, wait for
                            manual trigger (UI)
              ↓                   ↓
        Pull image
        Stop old container
        Start new container on shared network
              ↓
        NPM API: create/update proxy host
        → stage-dev-project.example.com
              ↓
        Health check
        → success: done, notify
        → failure: rollback, alert

Decisions

Decision	Choice	Rationale
Language	Go	Single binary, excellent Docker SDK, low resource usage
Web UI	SvelteKit (embedded in Go binary)	User's existing stack, lightweight
Reverse proxy	Nginx Proxy Manager	Already deployed, API available
Routing	Subdomain-based	No sub-path issues with SPAs
Image detection	Webhook + polling	Webhook for speed, polling as fallback
Config	YAML	Version-controlled, easy to edit
Deployment target	Same TrueNAS host	Docker socket mounted

Subdomain Convention

Stage	Pattern	Example
Dev	stage-dev-{project}.{domain}	stage-dev-web-app-launcher.dolgolyov-family.by
Release	stage-rel-{project}.{domain}	stage-rel-web-app-launcher.dolgolyov-family.by
Production	{custom}.{domain}	launcher.dolgolyov-family.by

Config Format

global:
  domain: dolgolyov-family.by
  network: staging-net
  npm:
    url: http://npm:81
    email: docker-watcher@dolgolyov-family.by
    password_env: NPM_PASSWORD
  subdomain_pattern: "stage-{stage}-{project}"
  notification_url: https://notify.dolgolyov-family.by/webhook

registries:
  gitea:
    url: https://git.dolgolyov-family.by
    type: gitea
    token_env: GITEA_TOKEN
  # github:
  #   url: https://ghcr.io
  #   type: github
  #   token_env: GITHUB_TOKEN

projects:
  web-app-launcher:
    registry: gitea
    image: gitea.dolgolyov-family.by/alexei/web-app-launcher
    port: 3000
    healthcheck: /api/health
    env_file: ./envs/web-app-launcher.env
    volumes: []
    stages:
      dev:
        tag_pattern: "dev-*"
        auto_deploy: true
      rel:
        tag_pattern: "v*"
        auto_deploy: false
      prod:
        tag_pattern: "v*"
        auto_deploy: false
        confirm: true
        promote_from: rel
        subdomain: launcher   # overrides pattern → launcher.dolgolyov-family.by

Project Structure

docker-watcher/
├── cmd/
│   └── server/
│       └── main.go                 # Entry point
├── internal/
│   ├── config/
│   │   ├── config.go               # YAML parsing, validation
│   │   └── config_test.go
│   ├── docker/
│   │   ├── client.go               # Docker Engine API wrapper
│   │   ├── container.go            # Create, start, stop, remove
│   │   └── client_test.go
│   ├── npm/
│   │   ├── client.go               # NPM API client (auth, CRUD proxy hosts)
│   │   └── client_test.go
│   ├── registry/
│   │   ├── registry.go             # Interface
│   │   ├── gitea.go                # Gitea registry implementation
│   │   ├── github.go               # GitHub Container Registry (future)
│   │   ├── poller.go               # Periodic tag polling
│   │   └── registry_test.go
│   ├── deployer/
│   │   ├── deployer.go             # Orchestrates full deploy flow
│   │   ├── rollback.go             # Rollback on failure
│   │   └── deployer_test.go
│   ├── health/
│   │   ├── checker.go              # HTTP health checks with retries
│   │   └── checker_test.go
│   ├── notify/
│   │   ├── notifier.go             # Webhook notifications
│   │   └── notifier_test.go
│   ├── webhook/
│   │   ├── handler.go              # Receive push events from Gitea/GitHub
│   │   └── handler_test.go
│   ├── api/
│   │   ├── router.go               # HTTP API for web UI
│   │   ├── projects.go             # Project endpoints
│   │   ├── deploys.go              # Deploy endpoints
│   │   └── middleware.go           # Auth, logging, CORS
│   └── store/
│       ├── store.go                # Deploy history, state (SQLite)
│       └── store_test.go
├── web/                            # SvelteKit frontend
│   ├── src/
│   │   ├── routes/
│   │   │   ├── +page.svelte        # Dashboard
│   │   │   ├── projects/
│   │   │   │   └── [id]/
│   │   │   │       └── +page.svelte # Project detail + deploy controls
│   │   │   └── settings/
│   │   │       └── +page.svelte    # Config view
│   │   ├── lib/
│   │   │   ├── api.ts              # API client
│   │   │   └── types.ts            # Shared types
│   │   └── app.html
│   ├── package.json
│   ├── svelte.config.js
│   └── vite.config.ts
├── docker-watcher.example.yaml
├── Dockerfile
├── docker-compose.yml
├── go.mod
└── go.sum

Implementation Phases

Phase 1: Foundation

Core infrastructure — config, Docker client, NPM client.

1. Go project init — go.mod, directory structure, dependencies
2. Config loader — parse YAML, validate, resolve env vars
3. Docker client — connect to socket, pull image, list/start/stop/remove containers, manage networks
4. NPM client — authenticate (JWT), create/update/delete proxy hosts, list existing hosts
5. Store — SQLite for deploy history and state tracking

Phase 2: Detection & Deployment

The core loop — detecting new images and deploying them.

6. Registry client — Gitea registry API: list tags, compare with last known
7. Poller — periodic check for new tags matching configured patterns
8. Webhook handler — HTTP endpoint receiving push events from Gitea CI
9. Deployer — orchestrate: pull → stop old → start new → NPM update → health check
10. Health checker — HTTP GET with retries and timeout
11. Rollback — on health check failure: stop new, restart old, revert NPM
12. Notifications — send webhook on deploy success/failure

Phase 3: Web UI

Dashboard for visibility and manual control.

13. API layer — REST endpoints for projects, stages, deploys, manual trigger
14. SvelteKit app — dashboard, project detail, deploy log, manual deploy button
15. Embed in Go — build SvelteKit to static, embed with go:embed, serve from Go
16. Real-time updates — SSE or WebSocket for deploy progress

Phase 4: Hardening

17. Blue-green deploys — start new, health check, swap, stop old (zero downtime)
18. Promote flow — enforce promote_from for production deploys
19. Auth on dashboard — basic auth or token-based
20. Graceful shutdown — drain in-progress deploys on SIGTERM
21. Structured logging — JSON logs with deploy context

Key Dependencies (Go)

• github.com/docker/docker — Docker Engine API
• github.com/go-chi/chi or net/http — HTTP routing
• gopkg.in/yaml.v3 — YAML config
• github.com/mattn/go-sqlite3 or modernc.org/sqlite — SQLite (CGo-free)
• github.com/robfig/cron — Polling scheduler

Docker Compose (self-deployment)

services:
  docker-watcher:
    image: docker-watcher:latest
    container_name: docker-watcher
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./docker-watcher.yaml:/app/config.yaml:ro
      - ./envs:/app/envs:ro
      - ./data:/app/data          # SQLite DB
    environment:
      - NPM_PASSWORD=${NPM_PASSWORD}
      - GITEA_TOKEN=${GITEA_TOKEN}
    networks:
      - staging-net

networks:
  staging-net:
    external: true

API Endpoints (Phase 3)

GET    /api/projects                    — list all projects with current status
GET    /api/projects/:id                — project detail + stage statuses
GET    /api/projects/:id/stages/:stage  — stage detail + deploy history
POST   /api/projects/:id/stages/:stage/deploy  — trigger manual deploy
POST   /api/projects/:id/stages/:stage/rollback — rollback to previous
GET    /api/deploys                     — recent deploys across all projects
GET    /api/deploys/:id/logs            — deploy log stream (SSE)
POST   /api/webhook/gitea              — Gitea push event receiver
POST   /api/webhook/github             — GitHub push event receiver (future)