The compose.yml file

The Docker Compose file is used to start the required services.

The initial compose file

The first step is to create a Docker Compose file. We will call it compose.yml.

services:
  postgres:
    image: postgres:16-alpine
    env_file:
      - .env
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kaneo -d kaneo"]
      interval: 10s
      timeout: 5s
      retries: 5

  kaneo:
    image: ghcr.io/usekaneo/kaneo:latest
    ports:
      - "5173:5173"
    env_file:
      - .env
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:5173/api/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s

volumes:
  postgres_data:

The services and volumes

Kaneo uses the following services:

• postgres: The PostgreSQL database.
• kaneo: The combined API and web container.

Additionally, the following volumes are used:

• postgres_data: The PostgreSQL data.

Required URL configuration

For the combined image, only KANEO_CLIENT_URL is required — KANEO_API_URL is derived automatically as KANEO_CLIENT_URL/api:

KANEO_CLIENT_URL=http://localhost:5173
POSTGRES_PASSWORD=changeme
AUTH_SECRET=                             # generate: openssl rand -hex 32

Set KANEO_API_URL explicitly only if you need to override the default (e.g. a reverse proxy changes the path).

This keeps the browser on one origin while the container proxies /api requests to the internal API process.

Notes on object storage

Kaneo uses S3-compatible object storage for private uploads in task descriptions and comments.

• Object storage is optional. Kaneo runs without it, but uploads in task descriptions and comments will be unavailable.
• For local/self-hosted setups, MinIO is the recommended option when you want uploads.
• The Kaneo API creates presigned upload URLs and the browser uploads files directly to the configured storage backend.
• Kaneo serves uploaded assets back through its own API, so the bucket does not need to be public.
• If you do not configure object storage, leave the S3_* variables unset.
• For a complete MinIO example and backend-specific setup notes, see the storage backends guide.

Optional MinIO service

Add this service and volume to your compose.yml only if you want uploads:

services:
  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    env_file:
      - .env
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio_data:/data
    restart: unless-stopped

volumes:
  minio_data:

Set the matching S3_* environment variables in your .env file. See the environment variables page.

Example .env values for MinIO

MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin

S3_ENDPOINT=http://minio:9000
S3_BUCKET=kaneo-uploads
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_REGION=us-east-1
S3_FORCE_PATH_STYLE=true

Create the bucket before testing uploads. With MinIO, you can do that from the MinIO Console at http://localhost:9001.

Using fs instead of MinIO

If you want to use fs, you can point the same S3_* variables at its endpoint instead of MinIO. Kaneo only needs an S3-compatible API endpoint, credentials, and a bucket.

When using fs, keep these differences in mind:

• Set S3_FORCE_PATH_STYLE=true.
• Create buckets through the S3 API or CLI, not through a web console.
• Browser uploads may require reverse-proxy CORS handling, because fs does not currently implement S3 CORS APIs.

After creating the compose file, the next step is to set up the environment variables.