---
name: homelab-apply
description: Deploy changes to the valhalla homelab. For application stacks (foundry, media, owncloud, etc.), commit and push — Portainer git-polls every 5 min. For the management plane (portainer, vault, watchtower, runner), Caddyfile, or .env on the server, use the apply-compose.ps1 helper. Use after editing any homelab config to get it deployed.
---

# homelab-apply

The repo is canonical. Different config layers deploy through different channels:

| Edit | Deployment channel | Lag |
|---|---|---|
| `stacks/<domain>/docker-compose.yml` or `stacks/<domain>/.env` | **git push** → Portainer polls every 5 min and redeploys that stack | up to 5 min |
| `Caddyfile` | git push triggers `.github/workflows/deploy.yml` → runner pushes file + `docker exec caddy caddy reload` | seconds (if workflow is enabled) |
| `portainer-compose.yml` (mgmt plane: portainer, vault, watchtower, runner) | `apply-compose.ps1 -Portainer` — Portainer can't manage itself | seconds |
| `vault.hcl` | `apply-compose.ps1 -Portainer` (bundled with mgmt plane push) | seconds |
| `.env` at `~/valhalla-lab/.env` (only used by mgmt plane + vault unseal) | `apply-compose.ps1 -EnvFile` | seconds |

## For application stack edits — just push

```powershell
git add stacks/media/.env
git commit -m "..."
git push
```

Portainer's per-stack auto-update will pick up the new commit within 5 minutes and redeploy. Watch progress:

```powershell
ssh -o BatchMode=yes ginnoir@valhalla "docker compose -f /data/compose/<id>/stacks/<domain>/docker-compose.yml ps"
```

Or just `docker ps` and filter by name. To force an immediate redeploy without waiting, trigger it from the Portainer UI ("Update the stack").

## For Caddyfile edits — push and wait for the runner

Workflow is gated by `paths: [Caddyfile, .github/workflows/deploy.yml]` so only Caddyfile commits trigger it.

If you don't want to wait (or the workflow is disabled), the manual fallback is:

```powershell
powershell -File apply-compose.ps1 -Caddy
```

This `scp`s the local Caddyfile to `/config/caddy/Caddyfile` and runs `docker exec caddy caddy reload --config /etc/caddy/Caddyfile`. Invalid Caddyfile → reload fails, old config keeps running; read the output.

## For management-plane edits

```powershell
powershell -File apply-compose.ps1 -Portainer    # portainer-compose.yml + vault.hcl + up -d
powershell -File apply-compose.ps1 -EnvFile      # ~/valhalla-lab/.env only
powershell -File apply-compose.ps1 -VaultUnseal  # unseal vault after restart (keys from .env)
```

No flags = `-EnvFile` + `-Caddy` (the two ad-hoc pushes you'd want for a quick manual deploy).

## Verify after applying

```powershell
ssh -o BatchMode=yes ginnoir@valhalla "docker ps --format 'table {{.Names}}\t{{.Status}}'"
ssh -o BatchMode=yes ginnoir@valhalla "docker logs --tail 50 <container>"
```

## Notes

- Compose is **v2** (`docker compose`, space).
- There is no monolithic `dc` alias anymore — each stack has its own compose dir under `/data/compose/<id>/stacks/<domain>/`. Address services by container name with `docker logs`, `docker exec`, etc. — `docker compose ...` only makes sense when you explicitly point at a per-stack compose file.
- A **GateGuard hook** blocks the first `Bash` and every `Write`/`Edit` until you state the user request + what the operation does/affects. State them, retry.