Installation

Pick the option that matches your setup. All three end with a working cpms-headless gateway listening on http://localhost:8080.

The fastest path — no Python toolchain on your machine.

docker run -d --name cpms-headless -p 8080:8080 \
  -e CPMS_API_KEY=hcpms_live_demo \
  ghcr.io/pipelet/cpms-headless:latest

Verify:

curl -H "X-API-Key: hcpms_live_demo" http://localhost:8080/api/v1/system/health

For the full minimal stack (gateway + ocpp-server + database), use Docker Compose — see Self-Hosting → Docker Compose Quickstart.

Install into a virtualenv:

python3 -m venv .venv
source .venv/bin/activate
pip install pipelet-cpms-headless wallecpms
CPMS_API_KEY=hcpms_live_demo python -m headless_cpms

The Python SDK wallecpms is a separate package on PyPI — install it independently if you only need the client.

Best for contributors and people running on platforms without our prebuilt images.

git clone https://github.com/pipelet/cpms-headless.git
cd cpms-headless
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
CPMS_API_KEY=hcpms_live_demo python -m headless_cpms

What you should see

[INFO] Headless CPMS Gateway started on http://0.0.0.0:8080
[INFO] OpenAPI docs available at /docs
[INFO] Loaded 1 API key(s)

Now hit the docs UI in your browser:

Swagger UI: http://localhost:8080/docs
ReDoc: http://localhost:8080/docs/redoc
Raw OpenAPI: http://localhost:8080/docs/openapi.json

These three are also rendered in this portal under API Reference → Headless CPMS, but the running instance is useful for hitting the Try it out button against your own data.

System requirements

Component	Minimum	Notes
CPU	1 vCPU	More cores → more concurrent OCPP connections
RAM	256 MB	512 MB+ recommended for production
Disk	100 MB	Plus your DB
Python	3.11	If running from source/pip
Database	MySQL 8 / PostgreSQL 14	Optional for the gateway alone; required for the full stack

What’s next

Make your first API call Walk through five real requests against your fresh install.

Set up authentication properly Generate real keys, rotate them, store them safely.