Native Binary Deployment

Native Binary Deployment

This guide explains how to run CPA Manager Plus as a native binary without Docker.

Native mode is still Manager Server mode: the binary serves /management.html, stores SQLite data locally, and uses the CPAMP admin key for login. It is not the old "external Usage Service for CPA panel mode" workflow.

---

Requirements

• CPA / CLI Proxy API runs separately
• CPA Management API is enabled
• You have the CPA Management Key
• The CPAMP data directory is persistent and backed up
• Only one CPAMP Manager Server consumes one CPA usage queue

Recommended CPA:

v7.1.39+

Minimum for HTTP usage queue:

v6.10.8+

---

Download

Download the package for your platform from:

https://github.com/seakee/CPA-Manager-Plus/releases

Common packages:

cpa-manager-plus_<version>_linux_amd64.tar.gz
cpa-manager-plus_<version>_linux_arm64.tar.gz
cpa-manager-plus_<version>_darwin_amd64.tar.gz
cpa-manager-plus_<version>_darwin_arm64.tar.gz
cpa-manager-plus_<version>_windows_amd64.zip
cpa-manager-plus_<version>_windows_arm64.zip

Check Linux architecture:

uname -m

Mapping:

x86_64  -> linux_amd64
aarch64 -> linux_arm64
arm64   -> linux_arm64

---

Run Manually

macOS / Linux:

tar -xzf cpa-manager-plus_vX.Y.Z_linux_amd64.tar.gz
cd cpa-manager-plus_vX.Y.Z_linux_amd64
./cpa-manager-plus

Windows PowerShell:

Expand-Archive .\cpa-manager-plus_vX.Y.Z_windows_amd64.zip -DestinationPath .
cd .\cpa-manager-plus_vX.Y.Z_windows_amd64
.\cpa-manager-plus.exe

Open:

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

If no admin key is configured, the process prints a generated cmp_admin_... key once. Save it immediately.

---

Data Location

By default, native packages create:

config.json
data/usage.sqlite
data/data.key

next to the binary.

Override with:

USAGE_DATA_DIR=/var/lib/cpa-manager-plus ./cpa-manager-plus

or:

USAGE_DB_PATH=/var/lib/cpa-manager-plus/usage.sqlite ./cpa-manager-plus

Back up:

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

---

Linux systemd Example

Install to a fixed directory:

sudo mkdir -p /opt/cpa-manager-plus /var/lib/cpa-manager-plus
sudo cp -a cpa-manager-plus_vX.Y.Z_linux_amd64/* /opt/cpa-manager-plus/
sudo useradd --system --no-create-home --shell /usr/sbin/nologin cpa-manager-plus
sudo chown -R cpa-manager-plus:cpa-manager-plus /opt/cpa-manager-plus /var/lib/cpa-manager-plus

Create /etc/systemd/system/cpa-manager-plus.service:

[Unit]
Description=CPA Manager Plus Manager Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=cpa-manager-plus
Group=cpa-manager-plus
WorkingDirectory=/opt/cpa-manager-plus
ExecStart=/opt/cpa-manager-plus/cpa-manager-plus
Restart=on-failure
RestartSec=3

Environment=HTTP_ADDR=0.0.0.0:18317
Environment=USAGE_DATA_DIR=/var/lib/cpa-manager-plus
# Recommended: provide a stable secret through an environment file or secret manager.
# Environment=CPA_MANAGER_ADMIN_KEY=replace-with-a-long-random-admin-key

[Install]
WantedBy=multi-user.target

Start:

sudo systemctl daemon-reload
sudo systemctl enable --now cpa-manager-plus
sudo systemctl status cpa-manager-plus

Logs:

journalctl -u cpa-manager-plus -f

---

First Setup

Open:

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

Enter:

Admin Key:          cmp_admin_... from logs, or your configured admin key
CPA URL:            http://127.0.0.1:8317, http://<cpa-host>:8317, or your CPA URL
CPA Management Key: CPA remote-management.secret-key

After setup, browser login uses the CPAMP admin key.

---

Upgrade

1. Stop the native process.
2. Back up the data directory, including data.key.
3. Extract the new package.
4. Copy over config.json and data/, or keep using USAGE_DATA_DIR / USAGE_DB_PATH.
5. Start the new binary.

systemd example:

sudo systemctl stop cpa-manager-plus
sudo cp -a /var/lib/cpa-manager-plus /var/lib/cpa-manager-plus.backup.$(date +%Y%m%d%H%M%S)
sudo cp -a cpa-manager-plus_vX.Y.Z_linux_amd64/* /opt/cpa-manager-plus/
sudo systemctl start cpa-manager-plus

---

Verification

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

Check configured, collector.lastError, lastConsumedAt, lastInsertedAt, and eventCount.