Projects

A project in kimbap is a docker-compose stack: a slug, a docker-compose.yml, an optional .env, and whatever domains you've routed to it.

Storage

Project files live directly on the filesystem, never in the database:

/var/lib/kimbap/projects/<slug>/
├── docker-compose.yml               # yours — kimbap never rewrites this
├── docker-compose.kimbap-labels.yml # auto-generated, only present once the project has domains
└── .env

kimbap's sqlite database (kimbap.db) only holds the project's metadata — slug, name, description, desired state (running/stopped), timestamps, and its domain records. The actual compose/env content is always read straight from disk, so you can inspect or back up a project's files with plain ls/cat/git, independent of kimbap.

The one file kimbap does generate and overwrite is docker-compose.kimbap-labels.yml — a compose override layering Traefik routing labels on top of your compose file (see Domains & TLS). It's regenerated whenever a project's domains change and is clearly marked DO NOT EDIT at the top; delete it (or remove all the project's domains) to detach a project from Traefik entirely.

Slugs

A slug is 1–63 lowercase alphanumeric characters and hyphens, and can't start or end with a hyphen (the same constraint Docker itself places on compose project names). It's used as:

The project's directory name under projects/.
The docker compose -p <slug> project name — so container names look like <slug>-<service>-1.

Slugs are immutable once a project is created.

Lifecycle

Action	What it does
Create	Validates the slug + compose YAML, writes the files, creates the DB row. Does not deploy.
Deploy	`docker compose up -d --remove-orphans` — pulls images, creates/starts containers, applies any compose/label changes since the last deploy.
Stop	`docker compose stop` — stops containers without removing them (fast to start again; volumes/networks untouched).
Restart	`docker compose restart`.
Update files	Overwrites `docker-compose.yml`/`.env` on disk. Does not redeploy — call Deploy afterward to apply.
Delete	`docker compose down` (removes containers + networks, not named volumes), then deletes the DB row and the project's directory.

Every lifecycle action is available from the web UI, the REST API (/api/projects/{slug}/...), and MCP tools (deploy_project, stop_project, etc. — see the API reference and MCP guide).

Logs

GET /api/projects/{slug}/logs?service=web&tail=200 (or the get_project_logs MCP tool) returns recent combined log output via docker compose logs --no-color -n <tail>. Omit service to get every service's logs interleaved.

Multi-file compose

kimbap always invokes compose with your file first and, if the project has domains, the generated label override second:

docker compose -p <slug> \
  -f docker-compose.yml \
  -f docker-compose.kimbap-labels.yml \
  --env-file .env \
  up -d

This is native compose behavior (later -f files layer on top) — nothing kimbap-specific to know beyond "don't hand-edit the labels file."