⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
---
title: "Install with Docker Compose"
description: "Run Kaneo and PostgreSQL, then sign in to your new instance."
---
This guide starts a local instance at `http://localhost:5173`. You need Docker with Compose V2 and a terminal. No repository clone is required.
<Tip>
Want Kaneo in production without being on call for it? A [managed instance](https://kaneo.app/pricing#managed-instance) gives you your own Kaneo in the EU, with backups and upgrades handled, from $299 a month.
</Tip>
## 1. Create a directory
```bash
mkdir kaneo
cd kaneo
```
Save the following as `compose.yml`:
```yaml
services:
postgres:
image: postgres:16-alpine
environment:
POSTGRES_USER: ${POSTGRES_USER:-kaneo}
POSTGRES_DB: ${POSTGRES_DB:-kaneo}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
volumes:
- postgres_data:/var/lib/postgresql/data
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", 'pg_isready -U "$${POSTGRES_USER}" -d "$${POSTGRES_DB}"']
interval: 10s
timeout: 5s
retries: 5
kaneo:
image: ghcr.io/usekaneo/kaneo:${KANEO_IMAGE_TAG:-2.28.3}
ports:
- "127.0.0.1:5173:5173"
env_file:
- .env
depends_on:
postgres:
condition: service_healthy
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "-Y", "off", "--quiet", "--spider", "http://127.0.0.1:5173/api/health"]
interval: 30s
timeout: 5s
start_period: 60s
retries: 3
volumes:
postgres_data:
```
This example pins Kaneo to a release so a pull does not unexpectedly upgrade it. See the [release notes](https://github.com/usekaneo/kaneo/releases) when choosing another version. To follow a release line instead, set `KANEO_IMAGE_TAG` to a major tag such as `2` or a major and minor tag such as `2.34`. These tags move to the newest matching release and only exist for lines released since they were introduced, so check the [available tags](https://github.com/usekaneo/kaneo/pkgs/container/kaneo) first. Pulling a newer image does not restart Kaneo; follow the [upgrade guide](/core/operations/upgrades) to apply it.
## 2. Add configuration
Run this twice to generate two different secrets:
```bash
openssl rand -hex 32
```
Create `.env` beside `compose.yml`. Replace both placeholders with the generated values:
```env
KANEO_IMAGE_TAG=2.28.3
KANEO_CLIENT_URL=http://localhost:5173
POSTGRES_DB=kaneo
POSTGRES_USER=kaneo
POSTGRES_PASSWORD=replace-with-the-first-generated-secret
AUTH_SECRET=replace-with-the-second-generated-secret
```
Keep this file private. On Linux or macOS, run `chmod 600 .env`.
The bundled image derives its database connection from `POSTGRES_*` and its API URL from `KANEO_CLIENT_URL`. You do not need to set `DATABASE_URL` or `KANEO_API_URL` for this setup.
## 3. Start and check the services
```bash
docker compose up -d
docker compose ps
curl --fail http://localhost:5173/api/health
```
Allow time for the first database initialization and migrations. Both services should become healthy. If they do not, check:
```bash
docker compose logs --tail=100 kaneo postgres
```
Open [localhost:5173](http://localhost:5173), create the initial account, and follow [Your first project](/core/index).
## 4. Make it available to your team
The port is bound to the host's loopback address. To serve Kaneo on a domain, follow the [Nginx and HTTPS guide](/core/reverse-proxy/nginx), then set:
```env
KANEO_CLIENT_URL=https://kaneo.example.com
```
Apply environment changes by recreating the container:
```bash
docker compose up -d --force-recreate kaneo
```
A plain restart keeps the old environment. If you use a proxy in another container, connect it to Kaneo's Docker network and proxy to `kaneo:5173` instead of the host's loopback address.
## Keep secrets in files
Instead of putting `POSTGRES_PASSWORD` and `AUTH_SECRET` in `.env`, you can mount them as Docker secret files. This requires a Kaneo release that includes `_FILE` support, so raise `KANEO_IMAGE_TAG` past `2.28.3` first.
Move the values you already use from `.env` into their own files:
```bash
mkdir -p secrets
sed -n 's/^POSTGRES_PASSWORD=//p' .env > secrets/postgres_password
sed -n 's/^AUTH_SECRET=//p' .env > secrets/auth_secret
chmod 700 secrets
chmod 644 secrets/*
```
Keep the current values. PostgreSQL sets its password only when it first initializes the `postgres_data` volume, so a new value in the file would no longer match the database. A new `AUTH_SECRET` would also sign everyone out. Generate fresh values with `openssl rand -hex 32` only for a new installation that has not started yet.
Compose mounts these files with their host ownership, and the containers read them as non-root users (UID 1001 for Kaneo, `postgres` for PostgreSQL). The files therefore need to be readable by other users, while the `700` directory keeps other accounts on the host from reaching them.
Remove `POSTGRES_PASSWORD` and `AUTH_SECRET` from `.env`. In `compose.yml`, replace the `POSTGRES_PASSWORD` line of the `postgres` service and add the secrets to both services:
```yaml
services:
postgres:
environment:
POSTGRES_USER: ${POSTGRES_USER:-kaneo}
POSTGRES_DB: ${POSTGRES_DB:-kaneo}
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
secrets:
- postgres_password
kaneo:
environment:
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
AUTH_SECRET_FILE: /run/secrets/auth_secret
secrets:
- postgres_password
- auth_secret
secrets:
postgres_password:
file: ./secrets/postgres_password
auth_secret:
file: ./secrets/auth_secret
```
Keep the other keys of each service as they are. For [custom OAuth](/core/social-providers/custom-oauth), mount the client secret the same way and set `CUSTOM_OAUTH_CLIENT_SECRET_FILE`. A direct value in `.env` takes precedence over its `_FILE` variable, so leave the direct variable unset. See the [environment variable reference](/core/installation/environment-variables#authentication) for how files are read and what happens when one is missing.
## Optional features
- [Silo](/core/installation/silo) stores images and attachments.
- [SMTP](/core/installation/environment-variables#smtp-configuration) delivers sign-in codes, invitations, and notifications.
- [Sign-in providers](/core/social-providers/custom-oauth) connect your identity provider.
PostgreSQL stays inside the Compose network. Do not publish its port for this deployment.
Before storing work you care about, set up [backups](/core/operations/backups). Use the [upgrade guide](/core/operations/upgrades) when changing versions.