Day-to-day operations¶

This covers what happens after your compose setup is running. For initial setup, see your project's deployment doc or Your project.

The first commandment¶

Thou shalt not edit compose.yml, Caddyfile, or Caddyfile-* by hand. They are generated and will be overwritten on the next run. Your edits will be erased. You will be sad. You were warned.

All persistent configuration lives in helmfile2compose.yaml (volume paths, excludes, service overrides, custom services) and your helmfile environment values. Projects that ship with helmfile2compose typically use a dedicated helmfile environment (e.g. environments/compose.yaml) for compose-specific values. Edit those, re-run, done.

Updating¶

Pull regularly. The compose deployment piggybacks on the same Helm charts used for Kubernetes. When charts are updated (version bumps, config fixes, new features), git pull and regenerating picks them up — no manual compose.yml editing.

After your maintainer updates the helmfile (chart versions, config changes), pull and regenerate:

git pull
python3 h2c-manager.py run -e compose
docker compose up -d

Or if your project ships a generate-compose.sh:

git pull
./generate-compose.sh
docker compose up -d

Existing helmfile2compose.yaml is preserved — only compose.yml, Caddyfile, configmaps/, and secrets/ are overwritten.

Data management¶

All persistent data lives under the configured data directory (volume_root in helmfile2compose.yaml, default: ./data).

To reset everything (fresh databases):

docker compose down
rm -rf ./data    # or your configured volume_root
docker compose up -d

Warning: Database init scripts (database/user creation) only run on first boot. Adding a new service that needs its own database may require a data reset.

compose.override.yml¶

Docker and nerdctl automatically load compose.override.yml alongside compose.yml — no -f flag needed.

Use it for local workarounds that shouldn't be in the generated compose:

services:
  my-backend:
    image: my-backend:fixed   # local rebuild for ARM64

This file is not generated by helmfile2compose — create it manually if needed.

Troubleshooting¶

Self-signed certificate warnings¶

For .local domains, Caddy uses its internal CA. Browsers show a certificate warning — click through it. To suppress warnings permanently, trust Caddy's root CA certificate.

Database not ready¶

Init jobs (migrations, superuser creation) use restart: on-failure and retry until the database is ready. This is brute-force purgatory — the job crashes, restarts, crashes again, and eventually the database deigns to accept it. The logs will be noisy. This is normal. Do not panic.

Check progress:

docker compose logs -f <service>-migrate

configmaps/ or secrets/ missing¶

If you ran docker compose up without first running helmfile2compose, the container runtime creates empty directories instead of the expected files. Fix:

docker compose down
rm -rf configmaps/ secrets/
./generate-compose.sh    # or re-run helmfile2compose manually
docker compose up -d

Re-generating from scratch¶

Delete the generated files and start over:

docker compose down -v
rm -f compose.yml Caddyfile Caddyfile-*
rm -rf configmaps/ secrets/
# Optionally reset config:
# rm -f helmfile2compose.yaml
./generate-compose.sh
docker compose up -d