deploy-service

Deploy a New Podman Service

Standard workflow for deploying a new containerised service. Services are managed with podman compose, with systemd units wrapping compose for process management where needed.

Step 0 — Clarify Before Starting

1. Service name — what to call the container and directory
2. Host — terminal or gate?
3. Image — full image reference (e.g., ghcr.io/someone/service:latest)
4. Network — which Podman network? (proxy for Traefik-exposed, internal for DB/cache, mcp for MCP tooling)
5. Public URL — does it need a Traefik route? What subdomain? Auth?
6. Secrets — does it need 1Password secrets?
7. Persistent data — any volumes needed?

Step 1 — Create the Compose File

Path: ~/projekt-apollo/services/<service-name>/compose.yml

services:
  <service-name>:
    image: <image>
    container_name: <service-name>
    restart: unless-stopped
    networks:
      - proxy          # or internal / mcp
    volumes:
      - ./data:/data   # adjust as needed
    environment:
      - KEY=${KEY}     # pull via 1Password Connect
    labels:
      # Traefik labels (omit if not public-facing)
      - "traefik.enable=true"
      - "traefik.http.routers.<service-name>.rule=Host(`<subdomain>.danctrl.net`)"
      - "traefik.http.routers.<service-name>.entrypoints=websecure"
      - "traefik.http.routers.<service-name>.tls=true"
      - "traefik.http.routers.<service-name>.tls.certresolver=cloudflare"
      - "traefik.http.routers.<service-name>.middlewares=crowdsec@file,authentik@file"
      # Use "crowdsec@file,local@file" for internal-only routes
      # Omit authentik@file if no SSO needed

networks:
  proxy:
    external: true

Step 2 — Start with Podman Compose

cd ~/projekt-apollo/services/<service-name>
podman compose up -d
podman compose logs -f    # watch startup

Step 3 — Systemd Integration (if needed)

Some services use systemd to manage themselves or require systemd for proper startup/restart behaviour. If needed, create a systemd service unit that wraps the compose invocation:

Path: ~/.config/systemd/user/<service-name>.service

[Unit]
Description=<Service Name>
After=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=%h/projekt-apollo/services/<service-name>
ExecStart=/usr/bin/podman compose up -d
ExecStop=/usr/bin/podman compose down
Restart=on-failure

[Install]
WantedBy=default.target

Then enable and start:

systemctl --user daemon-reload
systemctl --user enable --now <service-name>.service
systemctl --user status <service-name>.service

Ask Daniel whether this service needs a systemd unit — not all services require one.

Step 4 — Authentik (if SSO needed)

In Authentik admin (id.danctrl.net):

1. Create a Provider → Proxy Provider → Forward auth (single application)
2. Set external URL to https://<subdomain>.danctrl.net
3. Create an Application linked to the provider
4. Add to the embedded outpost

Step 5 — Verify

# Container is running
podman ps | grep <service-name>

# Traefik picked up the route
curl -s http://localhost:8080/api/http/routers | jq '.[].name' | grep <service-name>

# Endpoint responds
curl -I https://<subdomain>.danctrl.net

Step 6 — Update Brain

After a successful deploy, update the relevant reference file:

• skills/homelab-context/references/terminal.md or gate.md — add the container row
• skills/homelab-context/references/services.md — add the Traefik route

Common Pitfalls

• Always use podman compose not docker-compose
• Podman networks (proxy, internal, mcp) pre-exist — declare them external: true in compose
• Use systemctl --user, not sudo systemctl for user-level service units
• Secrets in environment variables must reference 1Password Connect, not plaintext values
• Config path convention: ~/projekt-apollo/services/<service-name>/