Backup and upgrade

By the end of this guide, you will know which data and secrets to preserve before replacing the application image, and which upgrade guarantees are unverified.

1. Identify the persistent data

For the README’s Docker setup, the kanesh-data volume is mounted at /data. SQLite uses DATA_DIR/kanesh.db unless SQLITE_PATH overrides it. In the Docker example this is /data/kanesh.db; the unconfigured development API uses api/.data/kanesh.db.

Preserve the /data volume or the configured SQLite database. For PostgreSQL or MySQL, back up the external database as well as any persistent data directory you use. File/image uploads are database blobs, so record exports do not replace a database backup.

Keep SETTINGS_ENCRYPTION_KEY with the backup. It encrypts secrets saved through Studio, such as the SMTP password, and takes precedence over the SECRET alias. Without either key, Studio cannot save secret settings. Changing the key means re-entering every saved secret.

Note: CSV/JSON exports exclude binary uploads and relation links and are paginated reads, not transactional backups.

2. Copy the Docker volume contents

The README uses docker cp to retrieve files from the named container. For that installation, this copies the directory mounted from kanesh-data to a local backup directory:

docker cp kanesh:/data ./kanesh-data-backup

This is a directory-copy example, not a documented live SQLite snapshot procedure. The allowed sources do not establish consistency guarantees for copying an active database or provide an external-database backup command.

3. Replace the application image

The current preview has no published image or release. Rebuild the API and Studio together from the Kanesh source root:

docker build --tag kanesh:local-review .

For an installation using a published image when one becomes available, pull its replacement before restarting. For the current source-built image, restart the application with the same database and data directory. The README’s run command reuses the named volume:

docker run --rm --name kanesh --publish 127.0.0.1:8080:8080 --volume kanesh-data:/data kanesh:local-review

Use this run command after the prior container has stopped. Preserve the external database configuration and encryption key if your installation uses them.

4. Check existing-install compatibility

Existing installations must rename former product-prefixed environment keys to the unprefixed names before restarting, keeping the same database and data directory. The README names HOST, PORT, DATA_DIR, DATABASE_DRIVER, DATABASE_URL, SQLITE_PATH, BOOTSTRAP_TOKEN, COOKIE_SECURE, MCP_ENABLED and SHUTDOWN_TIMEOUT. Studio development uses API_URL; production uses the same origin.

Resolve custom fields named created_at or updated_at before upgrading to the system timestamp contract. Schema version 2 leaves unknown old timestamps null. The former bare REST response format changed to the envelope described in REST API; update clients and rebuild API/Studio together.

Note: Downgrades are not supported. Back up the data volume and database before every upgrade so you can restore the previous version.

Troubleshooting

• Saved secrets need to be entered again: check that the original SETTINGS_ENCRYPTION_KEY or effective SECRET value was preserved.
• An existing installation still uses old environment names: rename the former product-prefixed keys before restarting and preserve its storage paths.
• Clients expect bare REST responses: update them for the data/meta or error/meta envelope.
• A record export lacks uploaded files: exports contain file IDs, not database blobs; preserve the database backup.

Next steps

• Review environment configuration
• Check database setup
• Understand record transfer limits