Skip to content

native.md

Latest commit

 

History

History
267 lines (186 loc) · 7.17 KB

native.md

File metadata and controls

267 lines (186 loc) · 7.17 KB
Raw

Native Packages

Use native packages when Docker is not part of your environment. They fit deployments already managed by systemd, launchd, Windows services, or another process supervisor.

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 the CPA-port panel" workflow.

If you only want to install the CPAMP native package, you can use One-Click Installer. The script does not install CPA natively; use Docker for a full new deployment.

Shortest Installation Path

  1. Confirm that CPA already runs and prepare its URL and CPA Management Key.
  2. Download the native package for your operating system and architecture from GitHub Releases.
  3. Extract and run cpa-manager-plus, or use the included background control script.
  4. Open http://<host>:18317/management.html.
  5. Log in with the generated CPAMP Admin Key from the logs and connect CPA.

For long-running production use, choose systemd, launchd, Windows Service Manager, or another process manager afterward.

Requirements

Before running it, prepare:

  • CPA / CLI Proxy API running separately.
  • CPA Management API enabled.
  • A CPA Management Key.
  • A persistent and backed-up CPAMP data directory.
  • Exactly one CPAMP Manager Server consuming one CPA usage queue.

Recommended CPA version:

v7.1.39+

Minimum for HTTP usage queue:

v6.10.8+

Download

Download the package for your platform from GitHub Releases.

Common package names:

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 cpamp_... key once. Save it immediately.

You can also set it explicitly.

macOS / Linux:

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

Windows PowerShell:

$env:CPA_MANAGER_ADMIN_KEY = 'replace-with-a-long-random-admin-key'
.\cpa-manager-plus.exe

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

When complete SQLite driver parameters are required, set only USAGE_DB_URL instead:

USAGE_DB_URL='file:///var/lib/cpa-manager-plus/usage.sqlite?_txlock=immediate&_pragma=journal_mode(DELETE)&_pragma=synchronous(EXTRA)&_pragma=busy_timeout(15000)&_pragma=foreign_keys(1)&_pragma=mmap_size(0)' ./cpa-manager-plus

USAGE_DB_URL and USAGE_DB_PATH are mutually exclusive; do not set both. See Manager Server Guide for the complete constraints.

Back up:

data/usage.sqlite
data/data.key
data/usage.sqlite-wal  # when WAL mode is active and the file exists
data/usage.sqlite-shm  # when WAL mode is active and the file exists

data.key decrypts the saved CPA Management Key. If it is lost, save the CPA connection again.

::: details Advanced: Linux systemd example

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:          cpamp_... 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.
  • CPA Management Key is stored server-side and encrypted.
  • New browsers no longer need the CPA Management Key.

Running In The Background

Native packages include background control scripts for start, status, logs, restart, and stop. The scripts write PID records and log files, and protect the default runtime directories with private permissions. See Native Background Control.

For production, you can also run the process through systemd, launchd, Windows Service Manager, or another process manager. Whichever method you use, make sure the data directory is persistent and backed up.

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, or USAGE_DB_URL. The URL and path cannot both be set.
  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

Upgrades do not require manual SQLite migration. Compatible migrations run automatically at startup.

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.

If the monitoring page is empty, continue with Request Monitoring Troubleshooting.