# Upgrade

Back up and test restoration before upgrading. Database migrations run at application startup. Downgrading application code against a migrated database is not supported; restore a matching backup when rolling back.

## From the personal 0.1 console

Version 0.2 defaults to `TEAM_MODE=1`. The earliest existing user becomes owner; other existing users become members. Original account, key and usage tables remain intact. New team keys use separate tables and local authentication: old personal keys are not automatically accepted by the team gateway.

Review the account inventory and deliberately register the connections your team may share. Issue new team keys and update each tool. [Provider enrollment](providers.md) describes the explicit account selection and private engine credentials. Nothing automatically imports every personal credential into the team catalog.

For a staged migration, `TEAM_MODE=0` retains the legacy personal routes with `ENGINES_ENABLED=1` and the optional engine override. Legacy mode does not have the new unified provider/allowance enforcement. Do not present legacy mode as the enterprise team gateway.

## Source or Linux service

```bash
git pull
npm test
npm run lint
```

Restart `node server.js` or your systemd service. Keep your private environment file and data directory in place. If running manually, load `.env` with `node --env-file-if-exists=.env server.js`.

## macOS

Pull the new checkout and run `bash scripts/install-macos.sh` again. The installer replaces managed application files and restarts the login service while preserving its `data`, `config.env` and logs. Use the same custom paths as the first installation. Removing the application with `~/.local/bin/jatevo uninstall` also preserves those files.

The `.pkg` workflow creates unsigned artifacts, not an automatic signed update channel. Installing a new setup app and running it applies the same source installer.

## Docker

API-only deployments:

```bash
git pull
docker compose up --build -d
```

Deployments using subscription engines:

```bash
git pull
docker compose -f compose.yml -f compose.engines.yml pull codexlb sidecar
docker compose -f compose.yml -f compose.engines.yml up --build -d
```

The engine override is required to retain the old 0.1.0 three-service topology. The new default Compose file is an independent API gateway. Both variants retain the existing named `data` volume; the optional engine override retains `codexlb-data`. Do not use `docker compose down -v` during an upgrade because it deletes persistent volumes.

The sidecar now runs as UID 1000, matching the console, so newly written authentication files remain readable by quota checks. If an older installation has root-owned sidecar configuration or auth files, stop it and repair ownership with the `init` service command in [Storage and backup](storage.md) before upgrading.

The engines remain pinned by version and digest. Review `engines.lock`, the corresponding Compose images and the checks in [Engines](upstream.md) together before changing a pin. Initialization preserves existing secrets and sidecar configuration; it does not overwrite a running engine's persisted configuration.

## Verify after upgrade

Check the console health endpoint, owner/member access, provider connection configuration, key restrictions and usage attribution with a small request. Optional engine boots should complete their bootstrap/settings checks. Review `CHANGELOG.md` for migration behavior and limitations in the version you install.