Installation
This page is the "properly, on a server" version of the Quick start.
What you need
- Docker with the Compose plugin. Nothing else — no Node.js, no database server, no web server. The image builds the frontend and bundles PocketBase, which serves the API, the database, authentication and the static files from a single container.
- An x86-64 processor. The image downloads PocketBase for
linux/amd64; on ARM (Raspberry Pi, a Mac with Apple silicon without emulation, ARM cloud servers) the build fails. Docker Desktop on an Apple silicon Mac usually manages through emulation (slower); for a real deployment choose x86-64. - A few hundred megabytes of disk for the image, plus whatever your attachments take.
- Ideally a machine that stays on. Recurring templates, daily summaries, deadline notices and timed reminders are driven by cron jobs inside the container. Nothing is silently skipped — if the server was off during the target hour, the jobs catch up later the same day — but a machine that is on in the morning delivers them at the hours you configured. After a reboot the container comes back on its own (
restart: unless-stopped).
No Docker yet? Pick your system
The rest of this page is the same for everyone — this part only gets your particular machine to the point where docker compose works.
Windows 10 / 11 — step by step
- Download Docker Desktop from docker.com and install it. The installer adds WSL 2 for you and asks for a restart once — let it restart.
- Start Docker Desktop and wait until it says Engine running in the bottom left. While it is still amber, the commands below will report that Docker is not running.
- Get the code: on the project page use the green Code → Download ZIP button and unpack it into, say,
C:\killbottleneck. (If you have Git,git cloneworks too.) - Open that folder in Explorer, click into the address bar, type
powershelland press Enter. A command line opens right in the correct folder. - Copy the configuration and start:powershell
Copy-Item .env.example .env docker compose up -d --build - Open
http://localhost:8090in your browser and create the admin account.
Things to watch out for on Windows:
- When the computer sleeps or shuts down, so does the instance. Daily summaries and deadline notices then catch up later the same day. For a team, a machine that stays on is the better host.
- Want to reach it from a phone or a colleague's computer? Use the machine's IP address (
ipconfig) instead oflocalhost, and when prompted, allow Docker through the Windows firewall for the private network. - If port 8090 is taken, change
KB_PORTin the.envfile. - Updating from a ZIP (without Git) is described in Updating → From a ZIP.
Linux (Ubuntu, Debian) — step by step
- Install Docker with the official script and add yourself to the
dockergroup so you do not needsudofor every command:bashAfter the second command log out and back in (or reboot) — otherwise the new group is not in effect yet and Docker reportscurl -fsSL https://get.docker.com | sudo sh sudo usermod -aG docker $USERpermission denied. - Check that it works:bash
docker run --rm hello-world - Then continue with Get the code below. There is nothing else to install — the image builds Node.js and the database into itself.
macOS
Download Docker Desktop for Mac (mind the right variant — Apple silicon vs Intel), start it, then continue with Get the code below. The same caveat as on Windows applies: a sleeping Mac means a sleeping instance. On Apple silicon the image is built through x86-64 emulation — it works, just slower.
Get the code
git clone https://github.com/tengolabs/killbottleneck.git
cd killbottleneckConfigure
cp .env.example .envThe defaults work as they are. The variables worth a look before the first start:
| Variable | Why now |
|---|---|
KB_PORT | If something already uses 8090. |
TZ | Set your zone (e.g. Europe/Prague), otherwise cron jobs and timed reminders run in UTC. |
KB_SETUP_CODE | Set it if the machine is reachable from the internet — otherwise anyone who knows the address can register. |
KB_NAME | Container name. A different name = a second instance next to the first on the same host (together with a different KB_PORT). |
KB_PUBLIC_URL | Needed for automations (so an agent knows where to report back) and behind a reverse proxy for the OAuth of AI agents — see HTTPS. |
The full list is in Environment variables.
Start
docker compose up -d --buildThe first build takes a few minutes (it compiles the frontend). Afterwards:
docker compose ps
docker compose logs -f killbottleneckOpen http://SERVER-IP:8090 — a fresh instance greets you straight with creating the administrator account (the title says Set up your instance; the first account becomes one automatically). What follows after the first sign-in is in the Quick start.
Stamp the version
Without it the instance reports itself as dev and the About dialog (menu by your name) does not offer the check for new versions. For a real deployment:
KB_VERSION=$(git describe --tags --dirty) docker compose up -d --buildAlways rebuild, never just restart
The application and all its server-side logic are baked into the image. After any change — new code, or an .env variable such as TZ — use:
docker compose up -d --builddocker compose restart will silently keep running the old build. This catches people out often enough to be worth repeating.
Where things live
| Path | What it is |
|---|---|
./pb_data | SQLite database and uploaded files. This is the only thing you must back up. |
./docker-compose.yml | Service definition. Overwritten by updates — do not edit it. |
./docker-compose.override.yml | Your local additions (a reverse proxy, extra ports, variables compose does not pass through). Not overwritten by updates. |
./.env | Your configuration. Not overwritten by updates. |
./backup.sh | The bundled backup and restore script. |
If you rename the compose service
docker-compose.override.yml refers to the service by name. Rename the service in docker-compose.yml without touching the override and docker compose config fails, so the stack will not come up at all.
The PocketBase admin UI
The instance also exposes the PocketBase superuser interface at http://SERVER-IP:8090/_/. Create the superuser account with the link from docker compose logs (see the screenshot above) or with docker compose exec killbottleneck /app/pocketbase superuser upsert EMAIL PASSWORD. You need it for exactly two things: configuring SMTP and low-level database inspection. Day-to-day administration happens in the application itself (Organization settings).
Do not change collections in the PocketBase admin UI
The database schema changes only through versioned migrations in the image (the server runs with --automigrate=0). If you add a field or a collection by hand in the admin UI, the change disappears after the next --build, but a record of it stays in the migration log and blocks the application of further migrations. Browse the data, leave the structure to updates.
Next
- Configuration — AI, sign-in, e-mail, limits
- HTTPS and a reverse proxy — reaching it from outside
- Backup and restore — before you put real work into it
- Updating — moving to a new version

