infra-controller

Python-based controller that discovers active apps and ensures required infrastructure services are present.

Services are expected to be managed as Docker Compose projects on the services server (e.g. /opt/grafana, /opt/prometheus).

Requirements

• Python 3.11+
• Docker and Docker Compose installed on the services server

Config

Preferred config file:

• /etc/infra-controller/config.toml

Copy the example config:

• config/controller.toml.example -> /etc/infra-controller/config.toml

Optional YAML config:

• config/controller.yml.example -> /etc/infra-controller/config.yml

Run

• infra-controller --once

systemd (event-driven)

To avoid running a daemon or polling timer, you can trigger a one-shot run whenever deployments update the active apps directory:

• enable path trigger: sudo systemctl enable --now infra-controller.path
• view logs: journalctl -u infra-controller-once.service -f

Remote app registration

Run infra-controller on the service server. When you deploy, create/update a registration file in /var/run/active-apps/ (this triggers the path unit).

Recommended (Forgejo runner on the web/app server):

• deploy app locally on the web/app server (docker compose or bare-metal)
• register app on the service server by streaming .infra.toml over SSH (no scp)

Example (from web/app server runner):

APP_NAME=my-app
ssh infractl@service-host \
  "cat > /var/run/active-apps/$APP_NAME.toml.tmp && mv /var/run/active-apps/$APP_NAME.toml.tmp /var/run/active-apps/$APP_NAME.toml" \
  < .infra.toml