Skip to main content
Use this guide only if your deployment still has separate ghcr.io/usekaneo/api and ghcr.io/usekaneo/web services. The bundled ghcr.io/usekaneo/kaneo image serves both on port 5173. Separate images remain available for deployments that need them. If you already use the bundled image, follow Upgrade Kaneo. For drim-managed deployments, see Migrate to drim.

​
Before changing the layout

  1. Back up the database, uploaded files, and configuration. Test that you can restore the database.
  2. Record the existing image version and choose a target release after reading its release notes.
  3. Keep the same Compose project name, database volume, PostgreSQL major version, database credentials, and AUTH_SECRET.
  4. Save copies of your Compose file, .env, and reverse-proxy configuration.
Changing the application layout does not require replacing PostgreSQL or moving its data. A newer Kaneo image can run database migrations, so an older image alone is not a complete rollback.

​
Replace the application services

In your existing Compose file, replace api and web with this service. Set KANEO_IMAGE_TAG in .env to your chosen release tag. Keep the existing database service and volumes.
This port binding assumes your reverse proxy runs on the host. If the proxy is another container, attach Kaneo to its network and point it at http://kaneo:5173 instead. Preserve any existing networks needed to reach the database or storage. Set KANEO_CLIENT_URL to your public web origin. In a same-origin deployment, remove an old KANEO_API_URL override that points to the separate API service: the bundled entrypoint derives KANEO_CLIENT_URL plus /api. Keep DATABASE_URL if it already identifies the correct database. Alternatively, the bundled image can derive it from POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_HOST (default postgres), and POSTGRES_PORT (default 5432). Preserve the existing values; changing an environment variable does not rename a database or reset its password. Keep your existing AUTH_SECRET. Generating a new one invalidates existing sessions.

​
Switch traffic

Validate the edited file and pull the selected image before stopping the old application:
Stop the old api and web services using your saved Compose file. Start the new service:
Update your proxy to send web, API, and WebSocket requests to port 5173. See Nginx and HTTPS. Remove dependencies on the old service names from other services in your Compose file. Check /api/health through the public URL, then sign in, open an existing project, edit a test task, and check an existing attachment. Remove the stopped API and web containers only after those checks pass. Keep your backups.

​
Migrating an old Helm values file

The bundled chart uses kaneo.* values. Old split-container charts used api.* and web.*. Compare your file with the values for your selected chart release before upgrading. Check the probes as well as their key names: current probes use /api/health and the named port kaneo. Keep your PostgreSQL PVC and existing credential secrets. The application image defaults to the chart’s appVersion when kaneo.image.tag is empty. Render the chosen chart with your migrated values and inspect its services, ingress, secrets, and database configuration before applying it. Choose the target chart version deliberately; the chart and application versions are aligned for current releases.

​
Recovery

If the new application never changed the database, restore the old application and proxy configuration. If it applied migrations, restore the matching database backup before returning to the old version. Follow the restore procedure and keep the failed database available for investigation.