add-service

Add a service

Checklist for adding a new HTTP service — preserves the system invariants (overview).

1. Create the guest

• Next free VMID (see inventory) and LAN IP 10.0.1.x.
• Default is now manual-first: pct create/qm create + per-service bootstrap (+ compose if containers are wanted) — see decisions. Helper-script LXCs are no longer the default for new services; QEMU only when the workload needs a full kernel.

2. DNS

• Technitium zone: add <name>.«MYDOMAIN» → A → «CADDY_TAILNET_IP». Update the table in dns.

3. Caddy

• Add a site block to /etc/caddy/Caddyfile on LXC 100:

<name>.«MYDOMAIN» {
  reverse_proxy 10.0.1.<x>:<port>
  tls {
    dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    resolvers 1.1.1.1
    propagation_timeout 10m
  }
}

• systemctl reload caddy (or restart). First request triggers the DNS-01 cert — allow a few minutes for propagation.
• Refresh the snapshot in caddyfile.

4. Auth (optional)

• If it supports OIDC: register a client in Pocket-ID (backed by lldap).

5. Storage (optional)

• Needs bulk data? Mount the Storage Box — mechanism per guest type in storage.

6. Non-HTTP needs (rare)

• If the service needs direct non-HTTP access (SSH etc.), join the guest to the tailnet — do NOT enable subnet routing (decisions).

7. Document

• Row in inventory and catalog, page in services/.