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

Services that are no longer required are stopped after grace_period_minutes (see config) using docker compose down.

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

Restricted SSH keys (recommended)

If you want to avoid giving CI a general shell on the services server, install the helper scripts to /usr/local/sbin (see install.sh) and restrict the runner key in authorized_keys.

Example (services server, ~infractl/.ssh/authorized_keys):

command="/usr/local/sbin/infra-register-stdin",no-pty,no-agent-forwarding,no-port-forwarding,no-X11-forwarding ssh-ed25519 AAAA... runner

For deregistration, use a separate key restricted to /usr/local/sbin/infra-deregister.