Troubleshooting

Which version am I running?

System → Info in the web UI shows the version, the platform (linux/amd64, darwin/arm64, …), the state directory, and how long the process has been up. There's a Check for updates button there too; it only asks the release site what's available — updating is still sudo kimbap update on the host (see Install).

From a shell: kimbap version, or curl -s http://localhost:8080/healthz, which reports the version without needing to log in.

kimbap won't start — "doesn't appear to point at this server yet"

(Only happens with KIMBAP_TRAEFIK_ENABLED=true.)

kimbap checks that KIMBAP_ADMIN_DOMAIN actually resolves to this host before it starts, so a wrong or not-yet-propagated DNS record fails fast with a clear reason instead of coming up and having certificate issuance fail later for no obvious cause. Two ways to fix it:

• Point the domain's DNS A/AAAA record at this server, wait for it to propagate, and sudo kimbap restart.
• If that domain isn't meant to be kimbap-managed at all, turn Traefik off: kimbap configure --set KIMBAP_TRAEFIK_ENABLED=false.

See Domains & TLS for the full walkthrough.

Ports 80/443 are already in use

(N/A if KIMBAP_TRAEFIK_ENABLED=false — nothing tries to bind them.)

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

(N/A if KIMBAP_TRAEFIK_ENABLED=false — there's no Traefik container.)

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

(N/A if KIMBAP_TRAEFIK_ENABLED=false — kimbap isn't issuing certificates; that's your own reverse proxy/tunnel's job in that mode.)

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/install/configure refuses to run / systemctl errors

kimbap start/stop/restart/status/install/uninstall/configure shell out to systemctl (or manage a systemd unit + system user) and require Linux + systemd. On macOS or Windows — or on Linux 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 on a real install, just without the systemd wrapper. See Install for the macOS/Windows walkthrough.

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.