Skip to main content

Documentation Index

Fetch the complete documentation index at: https://kaneo.app/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
  1. Docker Compose — replace the api and web services with kaneo
  2. Environment variables — KANEO_API_URL and DATABASE_URL are now optional
  3. 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 — kaneo waits for it 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

DATABASE_URL is derived from POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB 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 or a non-default 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 keyNew key
api.image.repositorykaneo.image.repository
api.image.tagkaneo.image.tag
api.image.pullPolicykaneo.image.pullPolicy
api.service.typekaneo.service.type
api.service.portkaneo.service.port
api.resourceskaneo.resources
api.env.clientUrlkaneo.env.clientUrl
api.env.authSecretkaneo.env.authSecret
api.env.existingSecretkaneo.env.existingSecret
api.env.disableRegistrationkaneo.env.disableRegistration
api.env.disablePasswordRegistrationkaneo.env.disablePasswordRegistration
api.env.databasekaneo.env.database
api.livenessProbekaneo.livenessProbe
api.readinessProbekaneo.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.