Docker Deployment

Docker Deployment

This guide explains how to deploy CPA Manager Plus with Docker. The Docker image contains the CPAMP Manager Server and the embedded management.html panel. It does not contain CPA / CLI Proxy API itself.

For new deployments, use the Manager Server-hosted panel:

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

Do not migrate the old CPA-Manager "CPA panel + external Usage Service URL" workflow. In Plus, CPA panel mode is a pure CPA panel and does not use Manager Server analytics.

---

Requirements

You need:

• A running CPA / CLI Proxy API instance
• CPA Management API enabled
• A CPA Management Key
• Persistent storage mounted to /data
• Exactly one CPAMP Manager Server consuming one CPA usage queue

Recommended CPA version:

v7.1.39+

Minimum for the HTTP usage queue:

v6.10.8+

CPA config must allow Manager Server to access the Management API:

remote-management:
  secret-key: "your CPA Management Key"
  allow-remote: true

---

Quick Start

docker run -d \
  --name cpa-manager-plus \
  --restart unless-stopped \
  -p 18317:18317 \
  -v cpa-manager-plus-data:/data \
  seakee/cpa-manager-plus:latest

Open:

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

On first setup, enter:

Admin Key:          cmp_admin_... from docker logs
CPA URL:            http://host.docker.internal:8317, http://cli-proxy-api:8317, or your CPA URL
CPA Management Key: CPA remote-management.secret-key

If CPA_MANAGER_ADMIN_KEY is not set, CPAMP generates an admin key and prints it once in the startup log:

docker logs cpa-manager-plus

After setup, new browsers log in with the CPAMP admin key. The CPA Management Key is encrypted and stored server-side.

---

Docker Compose

services:
  cpa-manager-plus:
    image: seakee/cpa-manager-plus:latest
    container_name: cpa-manager-plus
    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"
      # Recommended for managed deployments:
      # CPA_MANAGER_ADMIN_KEY: "replace-with-a-long-random-admin-key"
      USAGE_COLLECTOR_MODE: "auto"
      USAGE_BATCH_SIZE: "100"
      USAGE_POLL_INTERVAL_MS: "500"
      USAGE_QUERY_LIMIT: "50000"
    volumes:
      - cpa-manager-plus-data:/data
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:18317/health"]
      interval: 10s
      timeout: 3s
      retries: 3

volumes:
  cpa-manager-plus-data:

Start:

docker compose up -d

Use GitHub Container Registry if preferred:

ghcr.io/seakee/cpa-manager-plus:latest

---

CPA URL Examples

Scenario	CPA URL to enter during CPAMP setup
CPA and CPAMP in the same Compose network	http://cli-proxy-api:8317
CPA runs on Docker Desktop host	http://host.docker.internal:8317
CPA runs on Linux host, CPAMP in Docker	http://host.docker.internal:8317 plus --add-host=host.docker.internal:host-gateway
CPA is remote and reachable through HTTP queue	https://your-cpa.example.com

Linux host CPA example:

docker run -d \
  --name cpa-manager-plus \
  --restart unless-stopped \
  --add-host=host.docker.internal:host-gateway \
  -p 18317:18317 \
  -v cpa-manager-plus-data:/data \
  seakee/cpa-manager-plus:latest

Then use:

http://host.docker.internal:8317

Do not use 127.0.0.1 from inside a container unless CPA runs in the same container.

---

Data Persistence and Backup

Always mount /data.

Docker defaults:

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

Backups must include both SQLite files and data.key.

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

Why data.key matters:

• usage.sqlite stores usage data and encrypted CPAMP configuration
• data.key decrypts the saved CPA Management Key
• If data.key is lost, the saved CPA Management Key cannot be recovered; save the CPA connection again

---

Upgrade

Back up /data first.

docker pull seakee/cpa-manager-plus:latest
docker stop cpa-manager-plus
docker rm cpa-manager-plus
docker run -d \
  --name cpa-manager-plus \
  --restart unless-stopped \
  -p 18317:18317 \
  -v cpa-manager-plus-data:/data \
  seakee/cpa-manager-plus:latest

With Compose:

docker compose pull
docker compose up -d

---

Verification

curl http://127.0.0.1:18317/health
curl http://127.0.0.1:18317/usage-service/info

After setup:

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

Check:

configured
collector.lastError
lastConsumedAt
lastInsertedAt
eventCount

---

What Changed from CPA-Manager

Old CPA-Manager Docker docs used seakee/cpa-manager and described an external Usage Service for a CPA-hosted panel. In CPA Manager Plus:

• Image is seakee/cpa-manager-plus
• Container is usually cpa-manager-plus
• Full mode login uses the CPAMP admin key, not the CPA Management Key
• The CPA Management Key is encrypted with /data/data.key
• CPA panel mode is pure CPA-backed and does not configure external Manager Server analytics