> ## 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.

# Move to the bundled container

> Replace separate API and web containers while keeping your existing database and configuration.

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](https://kaneo.app/docs/core/operations/upgrades.md). For drim-managed deployments, see [Migrate to drim](https://kaneo.app/docs/core/installation/drim-migration.md).

## Before changing the layout

1. [Back up the database, uploaded files, and configuration](https://kaneo.app/docs/core/operations/backups.md). 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.

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
  kaneo:
    image: ghcr.io/usekaneo/kaneo:${KANEO_IMAGE_TAG:?Set KANEO_IMAGE_TAG in .env}
    env_file: .env
    ports:
      - "127.0.0.1:5173:5173"
    restart: unless-stopped
```

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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
docker compose config --quiet
docker compose pull kaneo
```

Stop the old `api` and `web` services using your saved Compose file. Start the new service:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
docker compose up -d kaneo
docker compose logs --tail=100 kaneo
```

Update your proxy to send web, API, and WebSocket requests to port 5173. See [Nginx and HTTPS](https://kaneo.app/docs/core/reverse-proxy/nginx.md). 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](https://github.com/usekaneo/kaneo/tree/main/charts/kaneo) before upgrading.

| Old setting | Bundled chart setting |
| - | - |
| `api.image.*` | `kaneo.image.*`, with repository `ghcr.io/usekaneo/kaneo` |
| `api.resources` | `kaneo.resources` |
| `api.env.*` | Corresponding settings under `kaneo.env` |
| `api.livenessProbe` / `api.readinessProbe` | `kaneo.livenessProbe` / `kaneo.readinessProbe` |
| Separate API and web services | One `kaneo.service`, port 5173 |
| Ingress targets for API and web | Bundled Kaneo service on port 5173 |

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](https://kaneo.app/docs/core/operations/backups.md) and keep the failed database available for investigation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.