Troubleshooting

Ports 80/443 are already in use

Traefik provisioning fails with something like:

Bind for 0.0.0.0:80 failed: port is already allocated

Something else on the host is already bound to port 80 or 443 — another reverse proxy, a previous Traefik/nginx/Caddy install, or another docker-compose project mapping those ports directly. Find it with:

ss -tlnp | grep -E ':80 |:443 '
docker ps --format '{{.Names}} {{.Ports}}'

and free the port (stop the other service, or remap it) before re-provisioning. kimbap doesn't attempt to seize ports from something else running on the host.

Traefik's Docker provider can't reach the Docker API

If Traefik logs something like:

Failed to retrieve information of the docker client and server host
error="Error response from daemon: client version 1.24 is too old.
Minimum supported API version is 1.40"

this is a compatibility gap between Traefik's bundled Docker client and an unusually new Docker Engine release that has dropped support for very old API versions. It's a Docker/Traefik interaction, not a kimbap bug. kimbap pins a Traefik image tag known to work against current Docker Engine releases (see internal/traefikctl/traefikctl.go) specifically because an older pin (v3.3) hit exactly this against a very recent Docker Engine build during development — if you hit it again on a newer Docker release:

• Confirm your Docker Engine version (docker version) isn't a pre-release/edge channel build.
• Try an even newer Traefik image tag (edit /var/lib/kimbap/traefik/docker-compose.yml's image: line, then docker compose -p kimbap-traefik up -d in that directory) — a newer Traefik release bundles a Docker client with wider version support. Report it too, so the default pin can be bumped.
• This does not affect the file-provider route that serves kimbap's own UI (see Domains & TLS) — only Docker-label-based routing for project containers.

A project won't deploy — "port is already allocated"

Two projects (or a project and something else on the host) are mapping the same host port directly in their compose files. This is unrelated to Traefik routing — it's a plain Docker port conflict. Either remove the direct host port mapping (route the service through a domain via kimbap instead, which doesn't need one) or pick a different host port.

Certificate issuance is stuck / never completes

Let's Encrypt's HTTP-01 challenge requires your domain's DNS to actually point at this host, and port 80 to be reachable from the public internet. Common causes:

• DNS hasn't propagated yet, or points at the wrong IP.
• A firewall/security group is blocking inbound port 80.
• You're testing locally (e.g. with *.localtest.me) — real certificate issuance is expected to fail in that case; it's only useful for verifying the routing mechanism itself, not for getting a real certificate. Set KIMBAP_ACME_STAGING=true while iterating, to avoid burning through Let's Encrypt's production rate limits.

Check Traefik's logs for the specific ACME error:

docker logs kimbap-traefik-traefik-1

kimbap start refuses to run / systemctl errors

kimbap start/stop/restart/status shell out to systemctl and require Linux + systemd. If you're testing kimbap somewhere without a real init system (a minimal container, some CI sandboxes), use kimbap run directly to run it in the foreground instead — that's the same process ExecStart=kimbap run invokes, just without the systemd wrapper.

Docker install/update seems to hang

get.docker.com runs a real apt-get update/install (or the equivalent for your distro) under the hood, which can legitimately take a minute or two depending on your mirror's speed. The install/update endpoint streams output live specifically so you can see it's still progressing rather than hung — if the UI/response goes quiet for more than ~5 minutes, something is genuinely stuck (check the host's own package-manager state: sudo apt-get update by hand, for instance).

I edited a project's compose file by hand on disk — will kimbap notice?

Yes for content, no for domains. kimbap always reads docker-compose.yml/.env fresh from disk (see Projects) — a hand-edit takes effect on the next Deploy. But docker-compose. kimbap-labels.yml is regenerated from the database whenever a domain changes, so a hand-edit to that file will be silently overwritten the next time you add/remove a domain — don't edit it.