Backup And Restore

CPAMP keeps request history, configuration, and encrypted credentials on the host. The common mistake is backing up only usage.sqlite and missing WAL/SHM files, data.key, or secret files in the install directory.

Required Backup Files

Back up these files as a set:

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

If your deployment directory contains custom configuration files, back them up too. With the one-click installer, also back up secrets/ under the install directory; full installation and env/secret-managed connections store the CPA Management Key in secrets/cpa-management-key.

Why data.key Is Required

CPA connections saved through setup or the panel encrypt the CPA Management Key with data.key before saving it to SQLite.

• If only usage.sqlite leaks, an attacker cannot directly read the CPA Management Key.
• If both usage.sqlite and data.key leak, the CPA Management Key can be decrypted.
• If data.key is lost, the saved CPA Management Key cannot be recovered. You must save the CPA connection configuration again.

If the CPA connection is managed by environment variables or secret files, the CPA Management Key is not written to SQLite. Back up the related secret files together with the data directory.

Docker Backup Example

If you use a named volume, stop the container first, then export through a temporary container:

docker stop cpa-manager-plus
docker run --rm \
  -v cpa-manager-plus-data:/data:ro \
  -v "$PWD":/backup \
  alpine \
  tar czf /backup/cpa-manager-plus-data.tgz -C /data .
docker start cpa-manager-plus

If you use a host directory mount:

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

Native Package Backup

Stop the process, then copy the data directory:

cp -a ./data ./data.backup

Windows PowerShell:

Copy-Item -Recurse .\data .\data.backup

Restore

1. Stop CPAMP.
2. Restore the full data directory.
3. Confirm that usage.sqlite and data.key come from the same backup.
4. If the CPA connection is env/secret-managed, also restore secrets/ from the install directory.
5. Start CPAMP.
6. Log in and check configuration, monitoring data, and collector status.

If restore produces decryption errors, first check whether data.key matches the SQLite database.

Move Manager Configuration Without Request History

If the old usage.sqlite is large and request history is no longer needed, start the replacement instance with an empty data directory and use the existing Manager configuration API to move the CPA connection, collector, Codex inspection, and External Usage Service settings. This does not copy usage_events, rollups, inspection run history, model prices, API Key aliases, or account-processing policy.

Export while the old instance is still reachable:

export OLD_CPAMP_URL='http://old-host:18317'
export OLD_CPAMP_ADMIN_KEY='cpamp_...'

curl -fsS \
  -H "Authorization: Bearer ${OLD_CPAMP_ADMIN_KEY}" \
  "${OLD_CPAMP_URL}/usage-service/config" \
  | jq '{config: .config}' \
  > manager-config.json
chmod 600 manager-config.json

manager-config.json may contain the CPA Management Key in plaintext. Treat it as a secret, do not commit it, and do not attach it to an issue.

Stop the old instance and start the new instance with an empty data directory. Record the new administrator key generated during first startup, then import the configuration:

export NEW_CPAMP_URL='http://new-host:18317'
export NEW_CPAMP_ADMIN_KEY='cpamp_...'

curl -fsS \
  -X PUT \
  -H "Authorization: Bearer ${NEW_CPAMP_ADMIN_KEY}" \
  -H 'Content-Type: application/json' \
  --data-binary @manager-config.json \
  "${NEW_CPAMP_URL}/usage-service/config"

The import validates the CPA Management API. After it succeeds, verify collector status and the related settings, then securely delete the exported file.

If the connection is managed through environment variables or secret files, the API reports source as env and an import cannot override the connection fields. Move CPA_UPSTREAM_URL, CPA_MANAGEMENT_KEY, or the matching secret files through the deployment environment instead. Administrator credentials are also outside the Manager configuration export; the new instance uses its newly generated or explicitly configured CPA_MANAGER_ADMIN_KEY.