Upgrading Korta Enterprise

Upgrades are automatic by default. Stop the manager, replace korta-server, and start it: it upgrades the database schema and its stored documents before serving requests, and logs each step:

applied database migration 0002_example

Back up first. With PostgreSQL, pg_dump the database. With files, copy KORTA_DATA_DIR. In both cases keep KORTA_VAULT_KEY (or data/vault-key): a backup cannot be read without it.

Upgrading as a separate step

Some teams let a database administrator, or a deploy job, upgrade the database. Set KORTA_MIGRATE=manual on the manager. It then refuses to start while upgrades are pending, and names them. Run the upgrade with the new release:

korta-server migrate status   # what is applied and what is pending
korta-server migrate          # apply the pending migrations

Both take the same environment as the manager (KORTA_DATABASE_URL). Only one manager or migration runs per database at a time; migrate waits for no one and fails if a manager is running, so stop the manager first.

What the manager guarantees

• Each migration runs in its own transaction: it applies completely or not at all. A failed upgrade leaves the database as it was before that migration, and the next start retries it.
• Skipping versions is safe: every migration between your version and the new one runs, in order.
• An older korta-server refuses to start on a database or documents written by a newer one, instead of corrupting them. To roll back, restore the backup you took before upgrading, then start the older release.
• If an applied migration does not match the release's copy, the manager refuses to start. This means the release was modified; use an official one.

Database privileges

The database user creates Korta's tables. The simplest setup is to make it the database's owner:

CREATE USER korta WITH PASSWORD '…';
CREATE DATABASE korta OWNER korta;

On PostgreSQL 15 and later, a user that does not own the database cannot create tables in public by default. The manager then stops with the statement to run, for example GRANT CREATE ON SCHEMA public TO korta.

Releases from before migrations existed upgrade the same way: the first migration recognises the table they created.

Users and access control

This release adds users, so the state format changes. There is no PostgreSQL schema migration, and older managers refuse the upgraded state.

After upgrading:

• Everyone is signed out once, because sessions now name a user.
• The administrator token keeps working, in the console and as a bearer token, with full access. Sign in with it, add your team on the Access page, and move scripts and CI to personal API tokens. Then keep the administrator token for emergencies.
• Role approvals need a second person: nobody can approve a role they last changed or planned. Set KORTA_FOUR_EYES=false if one person runs the manager. Roles and plans from before the upgrade have no recorded author, so anyone with approval access may approve them.
• Secrets have no scope, so any role can use them, as before. Limit production secrets on the Secrets page (env=prod, for example).

AWS launch reservations

The state format now records EC2 launch reservations and AWS account-bound plans. This upgrade adds no PostgreSQL schema migration. Older managers refuse the upgraded state. Back up the state and vault together before upgrading, and keep that state when retrying an interrupted AWS launch.

AWS networks, counts and Destroy

The state format changes again: it adds AWS networks and the resources Korta creates for each role, and records each instance's launch settings. Existing launch reservations keep working. This upgrade adds no PostgreSQL schema migration, and older managers refuse the upgraded state.

• Roles written with every AWS field keep working unchanged; new roles can leave image, subnet, security groups and key pair out.
• A role with AWS instances can no longer be deleted while they exist: destroy them from the role first.
• Grant the manager's IAM role the added permissions in AWS instances: images, instance types, VPCs, subnets, key pair import, security groups and termination.

AWS accounts in Settings

AWS accounts can now be added under Settings > AWS instead of the manager's environment, and one manager can use several accounts. The state format changes again (no PostgreSQL migration); older managers refuse it. Existing roles and instances keep using the manager's environment until you mark an account as default or give their network an account; the next plan then refuses to move existing instances to another account, so do that only for new roles and networks.

AWS networks built by roles

Roles can now build or adopt VPCs with an # AWS network section. The state format changes again (no PostgreSQL migration); older managers refuse it. Networks defined in Settings keep working and gain an optional list of private subnets. Grant each AWS account the network permissions listed in AWS instances before building networks.