Migration guide

What changed in v2.6.0

This release replaces the separate api and web containers with a single kaneo container. nginx runs on port 5173 and proxies /api/ requests to the internal Node API. Everything else (the database, volumes, environment variables) works the same. Three areas require changes when upgrading:

Docker Compose: replace the api and web services with kaneo
Environment variables: KANEO_API_URL and DATABASE_URL are now optional
Helm chart: all api.* and web.* values moved under kaneo.* (chart version 0.3.0)

Docker Compose

Before

services:
  postgres:
    image: postgres:16-alpine
    env_file:
      - .env
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  api:
    image: ghcr.io/usekaneo/api:latest
    ports:
      - "1337:1337"
    env_file:
      - .env
    depends_on:
      - postgres
    restart: unless-stopped

  web:
    image: ghcr.io/usekaneo/web:latest
    ports:
      - "5173:5173"
    env_file:
      - .env
    depends_on:
      - api
    restart: unless-stopped

volumes:
  postgres_data:

After

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 \"$${POSTGRES_USER:-kaneo}\" -d \"$${POSTGRES_DB:-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

volumes:
  postgres_data:

Remove the api and web service blocks and add the kaneo service. The postgres service is unchanged except for the added healthcheck, which kaneo waits for before starting.

Environment variables

KANEO_API_URL is now optional

Previously both KANEO_CLIENT_URL and KANEO_API_URL were required. Now KANEO_API_URL is derived automatically from KANEO_CLIENT_URL:

KANEO_API_URL = KANEO_CLIENT_URL + "/api"

Remove KANEO_API_URL from your .env unless you need to override it (for example, when a reverse proxy changes the API path). Before:

KANEO_CLIENT_URL=https://kaneo.example.com
KANEO_API_URL=https://kaneo.example.com/api

After:

KANEO_CLIENT_URL=https://kaneo.example.com
# KANEO_API_URL is set automatically to https://kaneo.example.com/api

DATABASE_URL is now optional

For the bundled image, DATABASE_URL is derived from POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, and the default Compose hostname if you leave it unset:

postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}

If you were setting DATABASE_URL explicitly with the same values, you can remove it. Keep it if you use an external database, a non-default hostname, or a host-native API process that should connect through localhost instead of the Compose hostname. Before:

POSTGRES_DB=kaneo
POSTGRES_USER=kaneo
POSTGRES_PASSWORD=changeme
DATABASE_URL=postgresql://kaneo:changeme@postgres:5432/kaneo

After:

POSTGRES_DB=kaneo
POSTGRES_USER=kaneo
POSTGRES_PASSWORD=changeme
# DATABASE_URL is derived automatically

AUTH_SECRET fallback behavior

If AUTH_SECRET is not set, the container generates a random 64-character hex secret at startup and prints a warning to stderr. This means sessions will not survive container restarts. Set a stable secret to avoid losing active sessions on restart:

openssl rand -hex 32

AUTH_SECRET=your_generated_secret_here

Helm chart (0.2.0 → 0.3.0)

Chart version 0.3.0 is a breaking change. All api.* and web.* value keys have moved under kaneo.*.

Changed value keys

Old key	New key
`api.image.repository`	`kaneo.image.repository`
`api.image.tag`	`kaneo.image.tag`
`api.image.pullPolicy`	`kaneo.image.pullPolicy`
`api.service.type`	`kaneo.service.type`
`api.service.port`	`kaneo.service.port`
`api.resources`	`kaneo.resources`
`api.env.clientUrl`	`kaneo.env.clientUrl`
`api.env.authSecret`	`kaneo.env.authSecret`
`api.env.existingSecret`	`kaneo.env.existingSecret`
`api.env.disableRegistration`	`kaneo.env.disableRegistration`
`api.env.disablePasswordRegistration`	`kaneo.env.disablePasswordRegistration`
`api.env.database`	`kaneo.env.database`
`api.livenessProbe`	`kaneo.livenessProbe`
`api.readinessProbe`	`kaneo.readinessProbe`
`web.*`	removed, web is bundled in the kaneo image

Example values migration

Before (values.yaml):

api:
  image:
    repository: ghcr.io/usekaneo/api
    tag: "2.5.0"
  service:
    type: ClusterIP
    port: 1337
  env:
    clientUrl: "https://kaneo.example.com"
    authSecret: "your-secret-here"

web:
  image:
    repository: ghcr.io/usekaneo/web
    tag: "2.5.0"
  service:
    type: ClusterIP
    port: 5173

After (values.yaml):

kaneo:
  image:
    repository: ghcr.io/usekaneo/kaneo
    tag: "2.6.0"
  service:
    type: ClusterIP
    port: 5173
  env:
    clientUrl: "https://kaneo.example.com"
    authSecret: "your-secret-here"

Upgrade command

helm upgrade kaneo kaneo/kaneo \
  --version 0.3.0 \
  --values your-values.yaml \
  --namespace kaneo

If you store values in a file, update the keys before running the upgrade. Helm will reject unknown keys and the deployment will fail if api.* or web.* keys remain.

Minimum working configuration

After upgrading, a minimal .env for Docker Compose requires three values:

KANEO_CLIENT_URL=http://localhost:5173
POSTGRES_PASSWORD=changeme
AUTH_SECRET=replace_with_output_of_openssl_rand_hex_32

Generate a stable secret with openssl rand -hex 32 and keep it persistent, or active sessions will be invalidated after a container restart. POSTGRES_DB and POSTGRES_USER default to kaneo if not set. KANEO_API_URL and DATABASE_URL are derived automatically.

Overview

Functional Guides

Installation

GitHub Integration

Gitea Integration

Integrations

Authentication Providers

Deployment & Operations

Migration

Migration guide

What changed in v2.6.0

Docker Compose

Before

After

Environment variables

KANEO_API_URL is now optional

DATABASE_URL is now optional

AUTH_SECRET fallback behavior

Helm chart (0.2.0 → 0.3.0)

Changed value keys

Example values migration

Upgrade command

Minimum working configuration

​What changed in v2.6.0

​Docker Compose

​Before

​After

​Environment variables

​KANEO_API_URL is now optional

​DATABASE_URL is now optional

​AUTH_SECRET fallback behavior

​Helm chart (0.2.0 → 0.3.0)

​Changed value keys

​Example values migration

​Upgrade command

​Minimum working configuration

What changed in v2.6.0

Docker Compose

Before

After

Environment variables

KANEO_API_URL is now optional

DATABASE_URL is now optional

AUTH_SECRET fallback behavior

Helm chart (0.2.0 → 0.3.0)

Changed value keys

Example values migration

Upgrade command

Minimum working configuration