From 7ca55bc94d0ba943b02b46cb339a7918c1e3a8d2 Mon Sep 17 00:00:00 2001 From: hibna Date: Sun, 2 Aug 2026 20:39:58 +0300 Subject: [PATCH] Add image-based deployment for control panels docker-compose.panel.yml deploys every service from a published image. A control panel writes only a compose file and an .env into its project directory, so the build: stanzas of docker-compose.yml cannot resolve their context there. CI pushes api, migrate, web and daemon images to the Gitea container registry on v* tags. The migrate stage ships as its own image because the panel compose runs it as a one-shot service before the API starts. The web port is named HOST_PORT: panels reverse-proxy "the" port of an installation and need to know which one that is when a stack publishes more than one. Co-Authored-By: Claude Opus 5 --- .github/workflows/ci.yml | 52 +++++++++++++++ INSTALLATION.md | 76 +++++++++++++++++++++ docker-compose.panel.yml | 141 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 269 insertions(+) create mode 100644 docker-compose.panel.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2db39f9..8fa142b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,6 +3,7 @@ name: CI on: push: branches: [main, develop] + tags: ["v*"] pull_request: branches: [main] @@ -95,3 +96,54 @@ jobs: - name: Build Daemon image run: docker build -f apps/daemon/Dockerfile -t gamepanel-daemon:ci . + + # --- Publish images (tags only) --- + # + # docker-compose.panel.yml deploys from these images, so the stack can be + # installed on a server that has no checkout of this repository — that is + # what a control panel needs. + # + # Plain `docker build` + `docker push` on purpose: no buildx or bake, so the + # job runs on the same self-hosted runner as the build test above. + # + # Requires a REGISTRY_TOKEN secret with package write scope. The registry is + # this Gitea instance's own container registry; the panel pulls from it. + publish: + name: Publish images + runs-on: ubuntu-latest + needs: [lint, daemon] + if: startsWith(github.ref, 'refs/tags/v') + env: + REGISTRY: gits.hibna.com.tr/hibna + steps: + - uses: actions/checkout@v4 + + - name: Registry login + run: | + printf '%s' "${{ secrets.REGISTRY_TOKEN }}" | + docker login gits.hibna.com.tr -u "${{ github.actor }}" --password-stdin + + - name: Resolve tag + run: echo "TAG=${GITHUB_REF#refs/tags/}" >> "$GITHUB_ENV" + + # The API Dockerfile carries the migration runner as its own stage; it + # has to be pushed as a separate image because docker-compose.panel.yml + # runs it as a one-shot service before the API starts. + - name: API + migrate + run: | + docker build -f apps/api/Dockerfile -t "$REGISTRY/gamepanel-api:$TAG" . + docker build -f apps/api/Dockerfile --target migrate -t "$REGISTRY/gamepanel-migrate:$TAG" . + docker push "$REGISTRY/gamepanel-api:$TAG" + docker push "$REGISTRY/gamepanel-migrate:$TAG" + + # VITE_API_URL is baked in at build time: the SPA calls /api on its own + # origin, which the image's nginx proxies to the api service. + - name: Web + run: | + docker build -f apps/web/Dockerfile --build-arg VITE_API_URL=/api -t "$REGISTRY/gamepanel-web:$TAG" . + docker push "$REGISTRY/gamepanel-web:$TAG" + + - name: Daemon + run: | + docker build -f apps/daemon/Dockerfile -t "$REGISTRY/gamepanel-daemon:$TAG" . + docker push "$REGISTRY/gamepanel-daemon:$TAG" diff --git a/INSTALLATION.md b/INSTALLATION.md index e202563..a5171b8 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -533,6 +533,82 @@ sudo ufw enable --- +## 4. Control Panel Deployment (pre-built images) + +Sections 2 and 3 build from a checkout on the server. A control panel does not +have one: it writes a compose file and an `.env` into its own project directory +and runs `docker compose up`. Anything with a `build:` stanza fails there — +the build context simply is not on disk. + +`docker-compose.panel.yml` exists for that case. Every service references a +published image, so the stack installs on a server that has never seen this +repository. It was written against [WebPanel](https://gits.hibna.com.tr/hibna/Source-WebPanel) +but nothing in it is panel-specific. + +### 4.1 Publish the images + +`.github/workflows/ci.yml` pushes four images to this Gitea instance's own +container registry on every `v*` tag: + +| Image | Contents | +|---|---| +| `gamepanel-api` | Fastify API | +| `gamepanel-migrate` | The API Dockerfile's `migrate` stage, run once before the API starts | +| `gamepanel-web` | SPA + nginx, built with `VITE_API_URL=/api` | +| `gamepanel-daemon` | Rust daemon | + +Add a `REGISTRY_TOKEN` repository secret with package write scope, then: + +```bash +git tag v0.1.0 && git push origin v0.1.0 +``` + +### 4.2 Prepare the host + +```bash +sudo mkdir -p /etc/gamepanel /var/lib/gamepanel/servers /var/lib/gamepanel/backups +sudo cp daemon-config.yml /etc/gamepanel/daemon-config.yml +sudo sed -i 's/CHANGE_ME_GENERATE_A_SECURE_TOKEN/'"$(openssl rand -hex 32)"'/' /etc/gamepanel/daemon-config.yml +``` + +Note the token you generated — the panel needs the same value when you register +the node. If the panel has a file manager, both steps can be done from it. + +### 4.3 Install + +Paste `docker-compose.panel.yml` into the panel's custom-compose screen and set: + +| Variable | Example | Notes | +|---|---|---| +| `REGISTRY` | `gits.hibna.com.tr/hibna` | Namespace holding the four images | +| `TAG` | `v0.1.0` | The tag you pushed | +| `HOST_PORT` | `8096` | **Not 80** if the panel's own web server owns it | +| `DB_PASSWORD`, `REDIS_PASSWORD` | `openssl rand -hex 24` | | +| `JWT_SECRET`, `JWT_REFRESH_SECRET` | `openssl rand -hex 64` | | +| `CORS_ORIGIN` | `https://panel.example.com` | Must match the address the browser uses | + +The published port is called `HOST_PORT` because panels commonly reverse-proxy +"the" port of an installation and need to know which one that is when a stack +publishes more than one. + +If the registry is private, the host needs `docker login` once — panels pull +anonymously otherwise. On Gitea the package can also be made public while the +repository stays private. + +### 4.4 Notes + +- **The daemon holds the Docker socket.** That is root-equivalent access to + every container on the machine, the panel's own containers included. Running + the daemon on a separate node — which the multi-node architecture is built + for — keeps the game hosts and the control plane apart. +- **Nothing publishes gRPC on a single host.** The API reaches the daemon over + the compose network as `daemon:50051`. A remote node runs the `daemon` + service on its own machine and publishes `50051` there. +- **Game server ports** are opened by the daemon on the host; a panel with a + default-deny firewall needs an explicit rule for the range you hand out. + +--- + ## Post-Installation ### First Login diff --git a/docker-compose.panel.yml b/docker-compose.panel.yml new file mode 100644 index 0000000..31eb0f9 --- /dev/null +++ b/docker-compose.panel.yml @@ -0,0 +1,141 @@ +# GamePanel — deployment from pre-built images. +# +# Unlike docker-compose.yml (which builds from source), every service here +# references a published image. That makes the stack deployable from a control +# panel that only writes a compose file plus an .env — WebPanel's "Custom +# Compose" screen, Portainer stacks, or a bare `docker compose up -d` on a +# server that has no checkout of this repository. +# +# Images are published by .github/workflows/ci.yml on every `v*` tag. +# +# REGISTRY=gits.hibna.com.tr/hibna TAG=v0.1.0 docker compose \ +# -f docker-compose.panel.yml up -d +# +# Two files must exist on the host before the first start: +# /etc/gamepanel/daemon-config.yml — node_token must match DAEMON_TOKEN +# /var/lib/gamepanel/{servers,backups} +# +# Serves plain HTTP on ${HOST_PORT}. Put a reverse proxy in front of it for TLS +# and a domain; WebPanel does this for you when you install with a domain. + +services: + # --- PostgreSQL --- + postgres: + image: postgres:16-alpine + restart: unless-stopped + environment: + POSTGRES_USER: ${DB_USER:-gamepanel} + POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD} + POSTGRES_DB: ${DB_NAME:-gamepanel} + volumes: + - postgres_data:/var/lib/postgresql/data + expose: + - "5432" + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-gamepanel}"] + interval: 10s + timeout: 5s + retries: 5 + + # --- Redis (rate limiting, session cache) --- + redis: + image: redis:7-alpine + restart: unless-stopped + command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD:?set REDIS_PASSWORD} + volumes: + - redis_data:/data + expose: + - "6379" + healthcheck: + test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"] + interval: 10s + timeout: 5s + retries: 5 + + # --- Schema migration + seed (runs to completion, then exits) --- + # + # A service that exits is not a failure here: `docker compose up --wait` — + # what WebPanel runs — treats a `service_completed_successfully` dependency + # correctly and reports the stack as healthy once api and web are up. + migrate: + image: ${REGISTRY:?set REGISTRY}/gamepanel-migrate:${TAG:?set TAG} + restart: "no" + depends_on: + postgres: + condition: service_healthy + environment: + DATABASE_URL: postgresql://${DB_USER:-gamepanel}:${DB_PASSWORD}@postgres:5432/${DB_NAME:-gamepanel} + + # --- API --- + api: + image: ${REGISTRY}/gamepanel-api:${TAG} + restart: unless-stopped + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy + migrate: + condition: service_completed_successfully + environment: + NODE_ENV: production + DATABASE_URL: postgresql://${DB_USER:-gamepanel}:${DB_PASSWORD}@postgres:5432/${DB_NAME:-gamepanel} + REDIS_URL: redis://:${REDIS_PASSWORD}@redis:6379 + PORT: 3000 + HOST: 0.0.0.0 + JWT_SECRET: ${JWT_SECRET:?set JWT_SECRET} + JWT_REFRESH_SECRET: ${JWT_REFRESH_SECRET:?set JWT_REFRESH_SECRET} + # Must match the address browsers use, otherwise the SPA's requests are + # rejected by CORS. + CORS_ORIGIN: ${CORS_ORIGIN:-http://localhost:8096} + RATE_LIMIT_MAX: ${RATE_LIMIT_MAX:-100} + RATE_LIMIT_WINDOW_MS: ${RATE_LIMIT_WINDOW_MS:-60000} + expose: + - "3000" + + # --- Web (nginx + SPA, also reverse-proxies /api and /socket.io) --- + # + # The published port is named HOST_PORT on purpose: WebPanel picks the port + # to reverse-proxy from that name. With two differently named *_PORT values + # and no HOST_PORT it cannot tell which one to publish and refuses to bind a + # domain. + web: + image: ${REGISTRY}/gamepanel-web:${TAG} + restart: unless-stopped + depends_on: + - api + ports: + - "${HOST_PORT:-8096}:80" + + # --- Daemon --- + # + # Single-host setup: the API reaches the daemon over the compose network as + # `daemon:50051`, so nothing needs to be published. For a *remote* node, run + # this service on that machine instead and publish 50051 there. + # + # This container controls the host's Docker engine through the socket below. + # That is root-equivalent access to every container on the machine, panel + # containers included — prefer a dedicated node for the daemon. + daemon: + image: ${REGISTRY}/gamepanel-daemon:${TAG} + restart: unless-stopped + depends_on: + - api + environment: + DAEMON_CONFIG: /etc/gamepanel/config.yml + # Game containers are created through the host's Docker socket, so their + # bind mounts are resolved by the *host*, not by this container. + DAEMON_HOST_DATA_PATH: ${DAEMON_DATA_PATH:-/var/lib/gamepanel/servers} + volumes: + - /var/run/docker.sock:/var/run/docker.sock + - ${DAEMON_DATA_PATH:-/var/lib/gamepanel/servers}:/var/lib/gamepanel/servers + - ${DAEMON_BACKUP_PATH:-/var/lib/gamepanel/backups}:/var/lib/gamepanel/backups + # Absolute path: a panel-managed deployment has no checkout of this repo, + # so the relative ./daemon-config.yml of docker-compose.yml is not there. + - ${DAEMON_CONFIG_FILE:-/etc/gamepanel/daemon-config.yml}:/etc/gamepanel/config.yml:ro + expose: + - "50051" + +volumes: + postgres_data: + redis_data: