Upgrade Process

The FinClaw upgrade flow follows the same skeleton as the first-time install: extract the new package → load images → init env → configure LLM → stop old → start new. The only real difference is in step 4: compare against the previous .env and migrate the changed values (the LLM config above all) into the new .env.

1. Upgrade Steps

Step 1 — Extract the new offline package

The latest release URL is provided by Finogeeks.

# On 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

Step 2 — Load images

./scripts/load-images.sh basic

Step 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

Step 4 — Diff against the old .env and migrate config (the LLM block is the key)

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

# Assume the old deploy lives at /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 side-by-side and locate the values you need to bring forward
diff "$OLD_DEPLOY/.env" "$NEW_DEPLOY/.env" | less

Minimum items to migrate / keep in sync:

Category	Variables	Bring forward from old .env
LLM (required)	LLM_PROVIDER / LLM_MODEL / LLM_BASE_URL / LLM_API_KEY	✅
Admin	ADMIN_EMAILS	✅
Concurrency limits	AI_INFRA_RS_*	✅ (only if you customized them)

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

Edit the new .env (the four LLM lines first):

vim .env

LLM_PROVIDER=openai
LLM_MODEL=<model name>
LLM_BASE_URL=<LLM endpoint>
LLM_API_KEY=<your API key>

Step 5 — Stop the old version

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

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

Step 6 — Start the new version

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

Step 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 a script that bundles steps 2–6 — loads images, copies the old .env, starts services, runs 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 basic

Flow: load new images → copy old .env (preserves JWT / LLM / internal token and every other customized value) → fleet.sh up → doctor.sh → upgrade summary.

After running, double-check the four LLM lines in the new .env.