Skip to content

v0.28.0-rc.1

Pre-release
Pre-release

Choose a tag to compare

View all tags
@antybubbs antybubbs released this 26 Aug 20:26
· 30 commits to dev since this release
Immutable release. Only release title and notes can be modified.
v0.28.0-rc.1
dbf34a6

Major Change: Upgrading Kaya from SQLite to dedicated PostgreSQL Container.

Kaya now uses PostgreSQL 16.14 as the supported production database.

Existing Kaya installations using SQLite can be migrated using the supplied upgrade Compose configuration. The migration preserves the original SQLite database and creates a verified backup before PostgreSQL is allowed to become authoritative.

Important: Plan a maintenance window before starting. Kaya will be unavailable during the one-time database migration.

Upgrading an Existing SQLite Installation to Kaya v0.28.0-rc.1

Kaya v0.28.0-rc.1 introduces a major database change:

Kaya now uses PostgreSQL 16.14 as the supported production database instead of SQLite.

These instructions are for existing Kaya installations that were deployed using Docker Compose and currently use SQLite.

Important

v0.28.0-rc.1 is a Release Candidate.

You must explicitly use:

ghcr.io/antybubbs/kaya:v0.28.0-rc.1

Do not use latest for this upgrade.

1. Go to your Kaya Docker Compose directory

Change into the directory containing your current Kaya docker-compose.yml.

For example:

cd /opt/kaya

Your actual path may be different.

2. Stop Kaya

Stop the existing installation cleanly:

docker compose down

Do not use

docker compose down -v

The -v option can remove Docker volumes and must not be used during this migration.

3. Back up your existing installation

Before changing anything, make a copy of your existing Kaya data directory:

cp -a ./data ./data.sqlite-before-v0.28.0-rc.1

If you use the default uploads directory, back that up as well:

cp -a ./uploads ./uploads.before-v0.28.0-rc.1

Keep these backups until you have confirmed that Kaya is running normally on PostgreSQL.

4. Replace your Docker Compose files with the v0.28.0-rc.1 versions

This release changes the Docker Compose stack because Kaya now includes a dedicated PostgreSQL container.

You must update your existing Compose files before running the migration.

Replace your current:

docker-compose.yml

with the docker-compose.yml supplied with v0.28.0-rc.1.

You will also need:

docker-compose.upgrade.yml

from the v0.28.0-rc.1 release.

Place both files in your Kaya installation directory.

Your directory should now contain at least:

docker-compose.yml
docker-compose.upgrade.yml
data/
uploads/

Do not delete your existing data directory.

That directory contains your SQLite database and other persistent Kaya data required for migration.

5. Make sure the RC image is used

The supplied Compose files default to the normal Kaya image unless KAYA_IMAGE is overridden.

For this Release Candidate, run all relevant commands with:

KAYA_IMAGE=ghcr.io/antybubbs/kaya:v0.28.0-rc.1

This ensures both Kaya and the migration service use the correct RC build.

6. Pull the v0.28.0-rc.1 image

Run:

KAYA_IMAGE=ghcr.io/antybubbs/kaya:v0.28.0-rc.1 docker compose pull

This will also pull the required PostgreSQL and supporting container images.

You can confirm the Kaya image with:

KAYA_IMAGE=ghcr.io/antybubbs/kaya:v0.28.0-rc.1 docker compose images

7. Run the one-time SQLite to PostgreSQL migration

Do not start Kaya normally yet.

Run:

KAYA_IMAGE=ghcr.io/antybubbs/kaya:v0.28.0-rc.1 \
docker compose \
  -f docker-compose.yml \
  -f docker-compose.upgrade.yml \
  run --rm sqlite-postgres-upgrade

This is the one-time migration process for existing SQLite installations.

During the migration, Kaya will:

  1. Validate the existing SQLite database.
  2. Check available storage.
  3. Create or reuse a verified pre-migration backup.
  4. Upgrade supported historical SQLite schemas where required.
  5. Start and prepare PostgreSQL 16.14.
  6. Copy the SQLite data into PostgreSQL.
  7. Validate row counts.
  8. Validate migrated data integrity.
  9. Validate foreign-key relationships.
  10. Repair PostgreSQL sequences where required.
  11. Validate the final PostgreSQL database.
  12. Mark PostgreSQL as authoritative only after successful validation.

Your existing SQLite database is retained.

Verified migration backups are stored under:

./data/backups/

8. Do not interrupt the migration

The migration may take several minutes or longer depending on:

  • SQLite database size
  • number of records
  • storage performance
  • available disk space
  • server performance

Large installations can perform substantial disk I/O during:

  • backup creation
  • SQLite schema preparation
  • PostgreSQL data copy
  • integrity validation

Important

Do not stop the migration simply because there is a period with little console output.

Wait for the migration to complete successfully or return an explicit error.

9. Start Kaya on PostgreSQL

Once the migration completes successfully, start Kaya normally using the RC image:

KAYA_IMAGE=ghcr.io/antybubbs/kaya:v0.28.0-rc.1 docker compose up -d

Check the containers:

docker compose ps

You should now see services including:

kaya
postgres
kaya-secure-send
kaya-guacd

Kaya and PostgreSQL should become healthy.

10. Check startup logs

Run:

docker compose logs --tail=100 kaya

A successful migrated installation should show something similar to:

Kaya database ready: engine=postgresql revision=20260818_02 migration_required=False

The important values are:

engine=postgresql
migration_required=False

11. Verify your data

Log in to Kaya and confirm your existing data is present.

Check at least:

  • users
  • dashboard data
  • network devices
  • DNS history
  • Remote Manager
  • hardware assets
  • audit logs
  • notifications
  • settings
  • uploaded files

Open:

About Kaya

and confirm the database backend is:

PostgreSQL

12. Reverse proxy users

If Kaya is accessed through a reverse proxy such as:

  • Nginx Proxy Manager
  • Nginx
  • Caddy
  • Traefik
  • HAProxy
  • Cloudflare Tunnel

make sure the reverse proxy that connects directly to Kaya is trusted.

Kaya uses:

FORWARDED_ALLOW_IPS

for this.

If your Compose setup already defines environment variables, set it there.

For example:

environment:
  FORWARDED_ALLOW_IPS: 127.0.0.1,192.168.1.3

Replace:

192.168.1.3

with the actual IP address of your reverse proxy.

After changing the setting, recreate Kaya:

KAYA_IMAGE=ghcr.io/antybubbs/kaya:v0.28.0-rc.1 \
docker compose up -d --force-recreate kaya

Then go to:

Site Administration → Security

and check:

Request came through a trusted proxy
Yes

If it shows No, the trusted proxy configuration is not correct.

13. Restart Kaya once

After confirming the migration and your data, restart Kaya:

docker compose restart kaya

Then check:

docker compose logs --tail=100 kaya

Kaya should continue to report:

engine=postgresql
migration_required=False

It should not attempt another SQLite migration.

If the migration fails

Kaya's migration process is designed to fail safely.

If the migration fails:

Do not delete anything.

Preserve:

./data/kaya.db
./data/kaya.db-wal
./data/kaya.db-shm
./data/backups/
./data/kaya-database-upgrade.json
./data/kaya-database-upgrade-report.json

Also preserve the PostgreSQL Docker volume.

Do not:

delete kaya.db
delete kaya.db-wal
delete kaya.db-shm
delete the migration marker
manually delete PostgreSQL data
drop the PostgreSQL schema
run ad-hoc SQL migration commands
run docker compose down -v

Capture the logs:

docker compose logs > kaya-v0.28.0-rc.1.log

Also preserve the terminal output from the migration command.

After successful migration

Once the migration completes successfully:

PostgreSQL becomes Kaya's authoritative database.

The original SQLite database remains as a retained migration/recovery artifact but is no longer used for normal operation.

Do not restore the old SQLite database over a working PostgreSQL installation.

The SQLite to PostgreSQL migration is a one-time process.

Do not rerun:

KAYA_IMAGE=ghcr.io/antybubbs/kaya:v0.28.0-rc.1 \
docker compose \
  -f docker-compose.yml \
  -f docker-compose.upgrade.yml \
  run --rm sqlite-postgres-upgrade

after a successful migration.

Staying on v0.28.0-rc.1

While testing this Release Candidate, start Kaya with:

KAYA_IMAGE=ghcr.io/antybubbs/kaya:v0.28.0-rc.1 docker compose up -d

If you run:

docker compose up -d

without specifying KAYA_IMAGE, the Compose file may fall back to:

ghcr.io/antybubbs/kaya:latest

For the RC test, continue explicitly using:

ghcr.io/antybubbs/kaya:v0.28.0-rc.1

until you deliberately move to another release.

Quick upgrade reference

# Enter the existing Kaya directory
cd /path/to/kaya

# Stop Kaya
docker compose down

# Back up the existing SQLite installation
cp -a ./data ./data.sqlite-before-v0.28.0-rc.1
cp -a ./uploads ./uploads.before-v0.28.0-rc.1

# Replace docker-compose.yml with the v0.28.0-rc.1 version
# Add docker-compose.upgrade.yml from v0.28.0-rc.1

# Pull the RC image
KAYA_IMAGE=ghcr.io/antybubbs/kaya:v0.28.0-rc.1 docker compose pull

# Run the one-time SQLite → PostgreSQL migration
KAYA_IMAGE=ghcr.io/antybubbs/kaya:v0.28.0-rc.1 \
docker compose \
  -f docker-compose.yml \
  -f docker-compose.upgrade.yml \
  run --rm sqlite-postgres-upgrade

# Start Kaya
KAYA_IMAGE=ghcr.io/antybubbs/kaya:v0.28.0-rc.1 docker compose up -d

# Check container health
docker compose ps

# Check startup
docker compose logs --tail=100 kaya

Successful startup should show:

engine=postgresql
migration_required=False

Never use docker compose down -v during this upgrade.

Assets 3
Loading
0 Join discussion