Skip to content

Architecture

Core components

Component Location Purpose
App registry /home/steam/automation/apps/*.conf Declares how each managed app is deployed and checked
Deploy wrapper /home/steam/automation/deployctl.sh Shared entrypoint for deploy, restart, status, health, rollback, and image update checks
Jenkins controller /home/steam/automation/jenkins Operator dashboard, scheduled jobs, webhook-triggered deploys
Onboarding helper /home/steam/automation/onboard-managed-app.sh Creates or updates app contracts, optional nginx config, and Jenkins deploy jobs
Host reverse proxy /etc/nginx/sites-available and /etc/nginx/sites-enabled Public ingress for each service
Host maintenance /home/steam/automation/systemd Timers and services that should run independently of Jenkins

Deployment model

Each managed app is represented by a shell contract file. The important fields are:

  • APP_ID: stable machine identifier used in job names and scripts
  • APP_DIR: working directory on disk
  • COMPOSE_FILE: compose file relative to APP_DIR
  • COMPOSE_PROJECT_NAME: explicit compose project name when needed
  • DEPLOY_MODE: compose-build for local source builds, compose-image for upstream image stacks
  • GIT_BRANCH: expected branch for auto-pull and webhook filtering
  • HEALTHCHECK_TYPE: http, container, or none
  • HEALTHCHECK_TARGET: HTTP endpoint when HEALTHCHECK_TYPE=http

The deploy flow is intentionally simple:

  1. Load the app contract.
  2. Run backup or pre-deploy hooks if configured.
  3. Update git or pull images when the contract allows it.
  4. Run docker compose up -d --build or docker compose up -d.
  5. Wait for the configured health signal.
  6. Run any post-deploy hook.

Reverse proxy model

Host nginx is the public entrypoint. Most apps follow the same pattern:

  • shared TLS certificate from /etc/nginx/ssl/ilgaming.xyz-crt.pem
  • per-app server_name
  • proxy_pass http://localhost:<port>
  • optional websocket headers on / or a dedicated socket path

The onboarding helper can now write and enable site configs because Jenkins mounts the host /etc/nginx tree. That helper validates syntax after writing the config.

Important limitation: nginx reload is still a separate host action. New configs can be generated and enabled automatically, but the running nginx service must still reload before a new vhost is live.