Upgrade Process

The FinClaw upgrade flow follows the same skeleton as the first-time install: extract the new package -> load images -> init env -> migrate .env config -> stop old -> start new. The only real difference is in step 4: compare against the previous .env and migrate the changed values into the new .env to avoid omissions. LLM model configuration is persisted in the database (maintained in the admin console) and is unaffected by upgrades - no migration needed.

1. Upgrade Steps

1. Extract the new offline package

The latest release URL is provided by Finogeeks.

# Enter the data disk
cd /data

# Extract (replace the filename with your actual version)
tar -xzf chatkit-offline-release-1.0.xx-linux-amd64-xxxxxxxx.tar.gz
cd chatkit-offline-release-1.0.xx-linux-amd64/deploy

2. Load images

./scripts/load-images.sh

3. Initialize the environment

This auto-generates .env from .env.example and mints JWT keys and internal tokens for the Identity service:

./scripts/init-env.sh

4. Diff against the old .env and migrate config

The freshly generated .env only contains defaults. Any value you customized in the previous version must be migrated into the new .env.

# Assume the old deploy directory is /data/chatkit-offline-release-1.0.<old>-linux-amd64/deploy
OLD_DEPLOY=/data/chatkit-offline-release-1.0.<old>-linux-amd64/deploy
NEW_DEPLOY=$(pwd)

# Compare the two .env files side-by-side to quickly locate the values to migrate
diff "$OLD_DEPLOY/.env" "$NEW_DEPLOY/.env" | less

Minimum items to migrate / keep in sync:

Category	Variables	From old .env
Admin	ADMIN_EMAILS	✅
Concurrency limits	AI_INFRA_RS_*	✅ (only if customized)

The JWT keys can use the freshly generated random values from init-env.sh; no need to force-reuse the old values. The only effect is that existing users have to sign in again; business data is unaffected.

Edit the new .env, migrating the diff items per the table above:

vim .env

5. Stop the old version

cd /data/chatkit-offline-release-1.0.<old>-linux-amd64/deploy
./scripts/fleet.sh down

down only stops containers; it does not delete data volumes (PostgreSQL / TimescaleDB / NATS / Redis / chatkit_ai_infra_data, etc.). The new version reuses these volumes, so conversation history, user data, and vector memory are all preserved.

6. Start the new version

cd /data/chatkit-offline-release-1.0.xx-linux-amd64/deploy
./scripts/fleet.sh up -d

7. Health check

./scripts/doctor.sh
curl http://127.0.0.1:26100/health

Expected: doctor.sh returns all ✅ / /health returns 200 OK. If individual services are slow on first start, wait 2–5 minutes and try again.

2. One-Shot Upgrade Script (Optional)

The release package ships an automated script that combines steps 2~6 above: auto-load images, copy the old .env, start services, run health checks.

# Run from the **new** deploy directory; point it at the old deploy directory
OLD_DEPLOY_DIR=/data/chatkit-offline-release-1.0.<old>-linux-amd64/deploy \
  ./scripts/upgrade-offline-release.sh

Script flow: load new images -> copy old .env (preserves JWT / internal token and every other customized value) -> fleet.sh up -> doctor.sh -> upgrade summary.

3. K8s Cluster Upgrade

Key differences:

• Base layer (PG/Timescale/Restate/Redis/TEI/NATS) is upgraded via ansible deploy.yaml re-run, rolling update
• Application layer is upgraded via helm upgrade rolling update