Skip to content

Day-to-day operations

The hard part is behind you — the manifests are converted, the stack boots, the containers talk to each other. Now you just need to keep the thing alive. 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 dekube.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

Your compose stack piggybacks on charts that someone else maintains. When they update, you update — that's the deal. You inherited a temple; you maintain it.

After your maintainer updates the helmfile (chart versions, config changes), pull and regenerate. No manual compose.yml editing.

If your project ships a generate-compose.sh (a wrapper script — check your project's README):

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

Or if your project uses dekube-manager directly (the package manager that downloads and runs helmfile2compose):

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

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

Data management

Everything you care about is in one directory. The generated files are ours; the data is yours.

All persistent data lives under the configured data directory (volume_root in dekube.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

For when the generated output is almost right but not quite, and you don't want to fight the generator.

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

See the dedicated Troubleshooting page — it has the longer knives for when these don't help.

Quick fixes for common issues:

  • Self-signed certificate warnings — for .local domains, Caddy uses its internal CA. Click through the browser warning, or trust Caddy's root CA certificate.
  • Database not ready — init jobs use restart: on-failure and retry until the database accepts them. Noisy logs on first boot are normal. Check progress: docker compose logs -f <service>-migrate
  • configmaps/ or secrets/ missing — if you ran docker compose up before helmfile2compose, Docker creates empty dirs. Fix: docker compose down && rm -rf configmaps/ secrets/ then regenerate.
  • Re-generating from scratch — docker compose down -v && rm -f compose.yml Caddyfile Caddyfile-* && rm -rf configmaps/ secrets/ then regenerate.