Migration from CPA Manager

Migration from CPA-Manager

This guide is for users moving from the old seakee/cpa-manager project to seakee/cpa-manager-plus.

The goal is to preserve historical usage events, model prices, API key aliases, and saved CPA connection settings where possible.

---

What Changed

Old CPA-Manager	CPA Manager Plus
seakee/cpa-manager	seakee/cpa-manager-plus
cpa-manager binary	cpa-manager-plus binary
Usage Service	Manager Server
Full mode login with CPA Management Key	Full mode login with CPAMP admin key
CPA Management Key stored in old setup data	CPA Management Key encrypted with data.key
CPA panel + external Usage Service URL	Not supported in Plus; use Manager Server-hosted panel

Compatible endpoints such as /usage-service/info and /usage-service/config still exist, but they are Manager Server compatibility endpoints in Plus.

---

Before You Start

1. Confirm CPA version. Recommended: v7.1.39+; HTTP usage queue minimum: v6.10.8+.
2. Locate the old data directory or volume.
3. Stop the old CPA-Manager service so SQLite WAL files are no longer being written.
4. Back up the full old data directory, including:

usage.sqlite
usage.sqlite-wal
usage.sqlite-shm

5. Decide the CPAMP admin key. Prefer setting CPA_MANAGER_ADMIN_KEY or CPA_MANAGER_ADMIN_KEY_FILE explicitly.

---

Docker Volume Migration

Old deployments commonly used:

services:
  cpa-manager:
    image: seakee/cpa-manager:latest
    volumes:
      - cpa-manager-data:/data

volumes:
  cpa-manager-data:

Start Plus with the same old volume:

services:
  cpa-manager-plus:
    image: seakee/cpa-manager-plus:latest
    restart: unless-stopped
    ports:
      - "18317:18317"
    environment:
      HTTP_ADDR: "0.0.0.0:18317"
      USAGE_DB_PATH: "/data/usage.sqlite"
      CPA_MANAGER_DATA_KEY_PATH: "/data/data.key"
      CPA_MANAGER_ADMIN_KEY: "replace-with-a-long-random-admin-key"
      USAGE_COLLECTOR_MODE: "auto"
    volumes:
      - cpa-manager-data:/data

volumes:
  cpa-manager-data:
    external: true

Do not accidentally start Plus with a new empty cpa-manager-plus-data volume if you expect old data to appear.

---

Host Directory Migration

Old example:

docker run -d \
  --name cpa-manager \
  -p 18317:18317 \
  -v /srv/cpa-manager-data:/data \
  seakee/cpa-manager:latest

Migration:

docker stop cpa-manager
cp -a /srv/cpa-manager-data /srv/cpa-manager-data.backup

docker run -d \
  --name cpa-manager-plus \
  --restart unless-stopped \
  -p 18317:18317 \
  -v /srv/cpa-manager-data:/data \
  -e CPA_MANAGER_ADMIN_KEY='replace-with-a-long-random-admin-key' \
  seakee/cpa-manager-plus:latest

Then open:

http://<host>:18317/management.html

and log in with the CPAMP admin key.

---

Native Package Migration

1. Stop the old cpa-manager process.
2. Back up the old program directory, especially data/usage.sqlite*.
3. Extract the cpa-manager-plus_<version>_<os>_<arch> package.
4. Copy the old data directory into the new package directory, or set USAGE_DATA_DIR / USAGE_DB_PATH to the old path.
5. Start with an explicit admin key:

CPA_MANAGER_ADMIN_KEY='replace-with-a-long-random-admin-key' ./cpa-manager-plus

---

First Startup Validation

Check startup logs:

• Save the generated cmp_admin_... value if you did not set CPA_MANAGER_ADMIN_KEY
• Confirm there are no SQLite, decrypt, or bootstrap errors

Then check:

curl -H "Authorization: Bearer <CPAMP_ADMIN_KEY>" \
  http://<host>:18317/status

In the panel:

1. Open Configuration -> CPA Manager Plus Configuration
2. Confirm the bound CPA URL
3. Confirm request monitoring, collection mode, and polling interval
4. Open Dashboard or Monitoring and verify historical data is visible

---

Backup Rules After Migration

Plus adds:

/data/data.key

From now on, backups must include:

usage.sqlite
usage.sqlite-wal
usage.sqlite-shm
data.key

If data.key is lost, encrypted CPA Management Key values cannot be recovered.

---

Rollback

Stop Plus before rollback.

The old CPA-Manager can read the main usage tables and old settings.setup, but it does not understand Plus admin credentials, bootstrap state, or data.key. Prefer rollback to the backup taken before first Plus startup.

---

Common Issues

• Old data is missing: Plus is probably using a new empty volume.
• Login returns 401: use the CPAMP admin key, not the CPA Management Key.
• Monitoring is empty: confirm CPA usage publishing, collector mode, CPA version, and that only one Manager Server consumes the queue.
• Decryption fails: confirm data.key was not lost or replaced.