Skip to content

Docker Deployment

Jump to bottom
seakee edited this page May 19, 2026 · 2 revisions

This guide explains how to deploy CPA-Manager Usage Service with Docker, and how to use it either as a full panel entry point or as an external Usage Service for the CPA built-in panel.

The CPA-Manager Docker image includes:

  • CPA-Manager Usage Service
  • Embedded management.html panel
  • SQLite-backed usage persistence
  • Proxy support for CPA Management API

Note: The Docker image does not include CLIProxyAPI itself.
You still need to deploy and run CLIProxyAPI separately.

1. When to Use Docker Deployment

Docker deployment is recommended if you want:

  • A quick way to start CPA-Manager Usage Service
  • A stable background service
  • Persistent SQLite data through Docker volumes
  • A single entry point for the management panel
  • Less manual work compared with native binary + systemd deployment

If your server has very limited disk space, see:

2. Deployment Modes

CPA-Manager Docker deployment can be used in two main modes.

Mode Entry URL Description Best For
Full Docker Mode http://<host>:18317/management.html Open the embedded panel from Usage Service New deployments, one entry point, fewer CORS issues
CPA Panel Mode http://<cpa-host>:8317/management.html Keep using CPA's built-in panel and configure an external Usage Service Existing CPA deployments

For new users, Full Docker Mode is recommended.

3. Requirements

3.1 CPA Is Already Running

You need to run CLIProxyAPI separately.

Typical CPA URL:

http://<cpa-host>:8317

Typical CPA panel URL:

http://<cpa-host>:8317/management.html

3.2 CPA Management Key

You need the CPA Management Key.

CPA-Manager Usage Service uses it to:

  • Verify the CPA connection
  • Proxy CPA Management API
  • Enable usage publishing
  • Consume the CPA usage queue
  • Authenticate later panel logins

3.3 Recommended CPA Version

Recommended:

CLIProxyAPI >= v7.1.0

CPA v7.0.7+ supports Redis Pub/Sub subscription for live usage events, and CPA v6.10.8+ supports the HTTP usage queue, which is easier to deploy and reverse proxy than RESP polling.

4. Full Docker Mode

This is the recommended mode.

Start the container:

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

Open:

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

On first setup, enter:

CPA URL
Management Key
Request Monitoring
Collection Mode
Poll Interval

Example:

CPA URL: http://192.168.1.10:8317
Management Key: <your-management-key>
Request Monitoring: enabled
Collection Mode: auto
Poll Interval: 500

After setup:

  • CPA URL and Management Key are saved in Usage Service SQLite
  • Request monitoring data is stored in /data/usage.sqlite
  • Later visits only require the Management Key
  • CPA management APIs are proxied through Usage Service
  • Usage statistics and request monitoring APIs read from Usage Service SQLite

5. Docker Compose

Create docker-compose.yml:

services:
  cpa-manager:
    image: seakee/cpa-manager:latest
    container_name: cpa-manager
    restart: unless-stopped
    ports:
      - "18317:18317"
    environment:
      HTTP_ADDR: "0.0.0.0:18317"
      USAGE_DATA_DIR: "/data"
      USAGE_DB_PATH: "/data/usage.sqlite"
      USAGE_COLLECTOR_MODE: "auto"
      USAGE_BATCH_SIZE: "100"
      USAGE_POLL_INTERVAL_MS: "500"
      USAGE_QUERY_LIMIT: "50000"
      USAGE_CORS_ORIGINS: "*"
    volumes:
      - cpa-manager-data:/data
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:18317/health"]
      interval: 10s
      timeout: 3s
      retries: 3

volumes:
  cpa-manager-data:

Start:

docker compose up -d

View logs:

docker logs -f cpa-manager

Check container status:

docker ps

Health check:

curl http://127.0.0.1:18317/health

6. CPA on Linux Host, CPA-Manager in Docker

If CPA runs directly on the Linux host and CPA-Manager runs inside Docker, the container cannot use 127.0.0.1 to reach the host CPA.

Use host.docker.internal:

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

During setup, use:

http://host.docker.internal:8317

Do not use:

http://127.0.0.1:8317

Inside the container, 127.0.0.1 means the container itself, not the host.

7. CPA Panel Mode

If you want to keep using CPA's built-in /management.html, you can run Docker only as the external Usage Service.

Steps:

  1. Start CPA.
  2. Start CPA-Manager Usage Service:
docker run -d \
  --name cpa-manager \
  --restart unless-stopped \
  -p 18317:18317 \
  -v cpa-manager-data:/data \
  seakee/cpa-manager:latest
  1. Open CPA's built-in panel:
http://<cpa-host>:8317/management.html
  1. Go to:
Configuration -> CPA-Manager Configuration
  1. Enable CPA-Manager Usage Service and enter:
http://<usage-service-host>:18317
  1. Save the configuration.

After saving:

  • Normal CPA management APIs still go to CPA
  • Usage statistics and request monitoring APIs go to Usage Service
  • The panel sends the current CPA URL and Management Key to Usage Service
  • Usage Service consumes CPA usage queue based on the saved configuration

8. How to Fill Usage Service URL

8.1 Direct IP and Port

If the service is reachable at:

http://1.2.3.4:18317

Then fill:

http://1.2.3.4:18317

8.2 Reverse Proxy

If Usage Service is behind Nginx or Caddy:

https://cpam.example.com

Then fill:

https://cpam.example.com

8.3 Do Not Use 127.0.0.1 by Mistake

If you open the remote CPA panel from your local browser:

http://127.0.0.1:18317

means your local computer, not the server.

Use the server IP, domain, or reverse proxy URL instead.

9. Data Persistence

In Docker deployment, the default data directory is:

/data

The default SQLite database is:

/data/usage.sqlite

Always mount /data:

-v cpa-manager-data:/data

Otherwise, usage data will be lost after the container is recreated.

10. Upgrade

Pull the latest image:

docker pull seakee/cpa-manager:latest

Stop and remove the old container:

docker stop cpa-manager
docker rm cpa-manager

Start again:

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

With Docker Compose:

docker compose pull
docker compose up -d

Back up the data volume before upgrading when possible.

11. Backup Data

For Docker named volume:

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

Restore:

docker run --rm \
  -v cpa-manager-data:/data \
  -v "$PWD":/backup \
  alpine \
  sh -c "cd /data && tar xzf /backup/cpa-manager-data-backup.tar.gz"

12. Common Environment Variables

Variable Default Description
HTTP_ADDR 0.0.0.0:18317 Usage Service listen address
USAGE_DATA_DIR /data Data directory
USAGE_DB_PATH /data/usage.sqlite SQLite database path
CPA_UPSTREAM_URL empty Optional preconfigured CPA URL
CPA_MANAGEMENT_KEY empty Optional preconfigured Management Key
CPA_MANAGEMENT_KEY_FILE /run/secrets/cpa_management_key Optional Management Key file
USAGE_COLLECTOR_MODE auto Collection mode: auto, subscribe, http, or resp; auto tries subscribe, then HTTP, then RESP
USAGE_BATCH_SIZE 100 Maximum queue records per batch
USAGE_POLL_INTERVAL_MS 500 Idle polling interval
USAGE_QUERY_LIMIT 50000 Maximum recent usage records returned
USAGE_CORS_ORIGINS * Allowed browser origins for CPA Panel Mode

Most users do not need to set CPA_UPSTREAM_URL or CPA_MANAGEMENT_KEY manually. The web setup flow is recommended.

13. Troubleshooting

13.1 Full Docker Mode Shows Login Instead of Setup

Usage Service has already been configured.

Enter the saved Management Key to log in.

To reset the setup, back up the data first, then remove or reset the SQLite database under /data.

13.2 Container Cannot Connect to Host CPA

On Linux, add:

--add-host=host.docker.internal:host-gateway

Then use:

http://host.docker.internal:8317

as the CPA URL.

13.3 No Request Monitoring Data

Check:

  1. CPA Management API is enabled
  2. Management Key is correct
  3. CPA usage publishing is enabled
  4. Usage Service /status is healthy
  5. Only one Usage Service consumes the same CPA queue
  6. CPA version is not too old
  7. USAGE_POLL_INTERVAL_MS is within the CPA usage queue retention window

13.4 Data Disappears After Rebuild

Check whether /data is mounted.

Correct:

-v cpa-manager-data:/data

Wrong:

docker run seakee/cpa-manager:latest

Without a persistent volume, SQLite data is lost when the container is removed.

13.5 CORS Error in CPA Panel Mode

For private deployments, the default is usually fine:

USAGE_CORS_ORIGINS=*

For public deployments, restrict it to the CPA panel origin:

USAGE_CORS_ORIGINS=https://cpa.example.com

Clone this wiki locally