Skip to content

Connect a Prox LXC as a Komodo Server

Register Docker LXCs (phoenix, sonarqube) so Core can pull /opt/homelab and deploy stacks via deploy-infra. Closes the audit P1 for Phoenix Server + periphery.

Preferred model: inbound periphery + GitOps [[server]]

Core dials each LXC on :8120. Servers are declared in services/komodo/resources.toml (no onboarding-key UI unlock required).

[[server]]
name = "phoenix"
[server.config]
address = "https://192.168.6.124:8120"
enabled = true

Use insecure_tls = true while Periphery serves its self-signed cert (default ssl_enabled = true).

Prerequisites

  • LXC is Ubuntu with Docker Engine + Compose plugin
  • Full git clone at /opt/homelab (not a partial services/ tree)
  • GitHub deploy key at /root/.ssh/github_deploy (and/or Git Provider PAT for PullRepo)
  • Age key at /etc/homelab/age-key.txt for SOPS decrypt of stack .env
  • Port 8120/tcp reachable from infra-services (192.168.6.17)

Install systemd periphery (inbound)

As root on the guest — omit --core-address so Periphery listens:

curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - \
  --connect-as="$(hostname)" \
  --root-directory=/etc/komodo

# Restrict who may dial in
printf '\nallowed_ips = ["192.168.6.17"]\nserver_enabled = true\nport = 8120\n' \
  >> /etc/komodo/periphery.config.toml

systemctl enable --now periphery
ss -lntp | grep 8120

--connect-as must match the [[server]] / [[stack]].server name (phoenix, sonarqube).

After resources.toml Sync applies the [[server]] blocks, confirm Servers show OK in the Komodo UI.

Alternate: outbound + onboarding key

Use when Core cannot reach :8120 on the LXC (strict firewall). Requires a brief KOMODO_UI_WRITE_DISABLED=false unlock to mint an O-… key, then:

curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - \
  --core-address="https://komodo.infra.realemail.app" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-REPLACE_ME"

Re-enable KOMODO_UI_WRITE_DISABLED=true afterward.

/opt/homelab checkout

# If replacing a snowflake tree, move it aside first (Docker volumes are separate)
mv /opt/homelab /opt/homelab.snowflake.bak
git clone git@github.com:notarealemail/homelab.git /opt/homelab
# Restore any host-only .env files from the bak tree into services/<name>/

Stacks and deploy-infra

Each LXC needs:

  • [[repo]] with server = "<hostname>" and path = "/opt/homelab"
  • [[stack]] with server = "<hostname>" and run_directory = "/opt/homelab/services/<name>"

deploy-infra pulls all repos (homelab, homelab-phoenix, homelab-sonarqube) before RunSync and BatchDeployStackIfChanged.