Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

6.5 KB
Raw Blame
---
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.