wocha/ocpp-cp-admin repository overview

⁠OCPP CP Admin

Charge Point Management System (CSMS) for Charge Point Operators (CPO), based on the OCPP 1.6 protocol.

OCPP CP Admin enables monitoring and managing electric vehicle charging infrastructure: charge point management, user management, charge transactions, real-time alerts, and an analytics dashboard.

⁠Table of Contents

• Features⁠
• Architecture⁠
• Prerequisites⁠
• Installation⁠
  • Node.js⁠
  • Docker⁠
  • Docker Compose⁠
  • Bare-metal (systemd)⁠
• Environment Variables⁠
• Configuration⁠
  • General⁠
  • Web Interface (WebUI)⁠
  • OCPP Server⁠
  • Notifications⁠
  • Google OAuth Authentication⁠
  • Legal Pages⁠
• TLS Certificates⁠
  • HTTPS — Web Interface⁠
  • WSS — OCPP Server⁠
• Getting Started⁠
• Roles and Permissions⁠
• OCPP 1.6 Protocol⁠
  • Supported Operations⁠
  • Charge Point Connection⁠
  • Security Profiles⁠
  • Heartbeat & Connection Monitoring⁠
• Notification System⁠
• Logging⁠
• Internationalization⁠
• Development Scripts⁠
• Database⁠
  • Backup⁠

⁠Features

⁠Charge Point Management

• Manual registration or automatic discovery of charge points
• Approval of pending charge points
• Assignment of charge points to sites
• Real-time monitoring (connector status, heartbeat, errors)
• Remote charge point configuration (GetConfiguration / ChangeConfiguration)
• OCPP message history (CALL / CALLRESULT / CALLERROR)

⁠Site and User Management

• Multi-site architecture
• Hierarchical roles: Admin, Manager, User
• Per-site and per-user authorization
• Local authentication (email / password) or Google OAuth 2.0
• Password reset via email with secure token

⁠Transactions and Charge Monitoring

• Active and completed transaction tracking
• Real-time data: energy (Wh), power (W), current (A per phase), state of charge (SOC %), temperature (°C), voltage (V per phase), frequency (Hz)
• Transaction history with filters
• CSV export of transactions
• Personal dashboard for users

⁠Error Event History

• Persistent log of hardware/network errors: StatusNotification faults, disconnections (after grace period), heartbeat timeouts
• Global view filterable by charge point, event type, OCPP version, and date range
• Accessible to managers and admins
• Real-time updates via WebSocket

⁠RFID Badge Management

• Badge creation and management (ID Tags)
• Automatic web tag generation for remote starts
• Expiration and authorization rejection tracking

⁠Charging Profiles

• Create and apply charging profiles on charge points via SetChargingProfile
• Supported purposes: ChargePointMaxProfile (global station power cap) and TxDefaultProfile (default transaction profile)
• Periodic (weekly) or relative scheduling with configurable power per time slot
• Targeted or full profile clearing via ClearChargingProfile
• Automatic re-application of managed profiles on charge point reconnection

⁠Connector Reservations

• Reserve a connector for a given RFID badge via OCPP 1.6 ReserveNow
• On-demand cancellation via CancelReservation
• Automatic expiration detection from StatusNotification

⁠Multi-Channel Notifications

• Email (SMTP via Nodemailer)
• Web Push (browser notifications via Service Worker)
• Pushover (mobile push notifications)
• 22 event types with role-based filtering
• Per-user and per-channel preferences

⁠Dashboard and Analytics

• Real-time statistics: connected charge points, active transactions, connector states
• Charging KPIs: energy, duration, frequency
• Historical charts (configurable date range)

⁠Security and Monitoring

• Connection loop detection (flapping)
• Duplicate identity detection (same identifier from multiple IPs)
• Rate limiting on APIs and authentication
• HTTP security headers (Helmet)
• Structured logging with file rotation

⁠Progressive Web Application (PWA)

• Installable on desktop and mobile (Web App Manifest)
• Responsive interface (mobile-first)
• Light/dark theme
• Push notifications via Service Worker
• /healthz endpoint for monitoring
• /metrics endpoint in Prometheus text format (optional bearer token protection)

⁠Architecture

┌─────────────────────────────────────────────────────────┐
│                     Browser / Mobile                    │
└──────────────────┬──────────────────────────────────────┘
                   │ HTTP/HTTPS
┌──────────────────▼──────────────────────────────────────┐
│         Express Web Server (Port 3000/3001)             │
│  ┌────────────────────────────────────────────────────┐ │
│  │ REST API                                           │ │
│  │ Auth, Sites, Users, Charge Points, Transactions    │ │
│  │ Notifications, Dashboard                           │ │
│  └────────────────────────────────────────────────────┘ │
└──────────────────┬──────────────────────────────────────┘
                   │
    ┌──────────────┼──────────────┐
    │              │              │
┌───▼─────┐  ┌─────▼────┐  ┌──────▼──────┐
│ SQLite  │  │ Sessions │  │ Real-time   │
│  (DB)   │  │ (SQLite) │  │ broadcast   │
└─────────┘  └──────────┘  └─────────────┘
                   │
┌──────────────────▼──────────────────────────────────────┐
│         OCPP Server (WS Port 9000 / WSS Port 9001)     │
│  ┌────────────────────────────────────────────────────┐ │
│  │ OCPP 1.6 RPC                                       │ │
│  │ Authentication (password + client certificate)     │ │
│  │ Handlers: Boot, Authorize, Transactions ...        │ │
│  │ Remote commands: RemoteStart, ChangeConfig         │ │
│  └────────────────────────────────────────────────────┘ │
└──────────────────┬──────────────────────────────────────┘
                   │ WebSocket OCPP 1.6
          ┌────────▼────────┐
          │   EVSE Stations │
          └─────────────────┘

⁠Tech Stack

⁠Prerequisites

• Node.js >= 22
• npm >= 10
• Or Docker / Docker Compose

⁠Installation

⁠Node.js Installation

# Clone the repository
git clone <repository-url>
cd ocpp-cp-admin

# Install dependencies
npm install

# Copy the sample configuration
cp config/config.sample.json config/config.json

Edit config/config.json according to your needs (see the Configuration⁠ section).

⁠Docker Installation

The image is available on GitHub Container Registry and Docker Hub:

docker pull ghcr.io/wocha-fr/ocpp-cp-admin:latest
# or
docker pull wocha/ocpp-cp-admin:latest

Or build the image locally:

docker build -t ghcr.io/wocha-fr/ocpp-cp-admin .

Four Docker Compose files are available in the docker/ folder, suited for different deployment scenarios:

# Example: full stack with Traefik
docker compose -f docker/docker-compose.yml up -d

# Example: app only HTTP
docker compose -f docker/docker-compose.http.yml up -d

Traefik-based stacks include:

• Reverse proxy with host-based routing (cpadmin.local, ws.cpadmin.local)
• FTP server for charge point diagnostics retrieval
• Let's Encrypt support (TLS variant)
• TCP passthrough for OCPP WSS with client certificate authentication (TLS variant)

See docker/README.md⁠ for details on each compose file.

⁠Bare-metal Deployment (systemd)

For servers running without Docker, a ready-to-use systemd unit is provided in scripts/.

1. Create a dedicated user and deploy the application:

sudo useradd --system --no-create-home --shell /usr/sbin/nologin ocpp-cp-admin
sudo mkdir -p /opt/ocpp-cp-admin
sudo cp -r . /opt/ocpp-cp-admin
sudo chown -R ocpp-cp-admin:ocpp-cp-admin /opt/ocpp-cp-admin
cd /opt/ocpp-cp-admin && sudo -u ocpp-cp-admin npm ci --omit=dev

2. Configure environment variables:

# Copy the template and fill in your values
sudo mkdir -p /etc/ocpp-cp-admin
sudo cp scripts/env.example /etc/ocpp-cp-admin/env
sudo nano /etc/ocpp-cp-admin/env
sudo chmod 600 /etc/ocpp-cp-admin/env

# Then uncomment the EnvironmentFile= line in the unit file:
# EnvironmentFile=/etc/ocpp-cp-admin/env

See scripts/env.example⁠ for all available variables.

3. Install and start the service:

sudo cp scripts/ocpp-cp-admin.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now ocpp-cp-admin

# View logs
journalctl -u ocpp-cp-admin -f

Exposed Ports:

Volumes:

The /metrics endpoint exposes Prometheus-format metrics (chargepoints, transactions, connectors by status, uptime, heap). It is accessible without authentication by default; set metrics.bearerToken (or CPADMIN_METRICS_TOKEN) to require a bearer token.

On first startup, if config/config.json does not exist, it is automatically created from config.sample.json.

The entrypoint runs as root to seed default files and fix volume permissions, then drops privileges to a dedicated non-root user (app) via su-exec.

⁠Environment Variables

Values from config.json can be overridden by environment variables. The JSON file remains the base configuration; environment variables take precedence when set.

⁠Deployment / URLs

⁠General Configuration

⁠Feature Activation

⁠OCPP Behavior

⁠Mail Configuration

⁠WebPush Configuration

⁠Pushover Configuration

⁠Notification Defaults

⁠Google Auth Configuration

⁠Prometheus Metrics

⁠Configuration

The configuration file is config/config.json. In development mode (NODE_ENV=development), config/config.dev.json is used if it exists.

Configuration values can be overridden by environment variables (see the Environment Variables⁠ section).

⁠Configuration Editor (UI)

Administrators can edit the configuration directly from the web interface via Settings → Configuration. The editor displays all parameters organized by section in a table with three columns:

• File value — the value currently stored in config.json
• Env. variable — the associated environment variable name and its current value (or not set if undefined)
• New value — editable field pre-filled with the effective value (env override takes precedence over the file value)

Required fields are validated before saving. The application restarts automatically after a successful save.

⁠General

⁠Web Interface (WebUI)

"webui": {
  "httpHost": "localhost",
  "httpPort": 3000,
  "trustProxy": false,
  "publicUrl": "http://localhost:3000",
  "sessionSecret": "",
  "https": {
    "enabled": false,
    "httpsPort": 3001,
    "certFile": "certs/server.crt",
    "keyFile": "certs/server.key"
  }
}

⁠OCPP Server

"ocpp": {
  "host": "0.0.0.0",
  "wsPort": 9000,
  "strictMode": true,
  "callTimeoutSeconds": 45,
  "autoAddUnknownChargepoints": false,
  "pendingUnknownChargepoints": true,
  "ocppWsUrl": "ws://ws.cpadmin.local:9000",
  "diagnosticsLocation": "ftp://example.com/diagnostics",
  "v16":  { "enabled": true },
  "v201": { "enabled": false },
  "wss": {
    "enabled": false,
    "wssPort": 9001,
    "strictClientCert": false,
    "ocppWsUrl": "wss://ws.cpadmin.local:9001",
    "rsa": { "certFile": "...", "keyFile": "..." },
    "ecdsa": { "certFile": "...", "keyFile": "..." },
    "caFile": ""
  }
}

⁠Notifications

"notifs": {
  "authRejectThreshold": 3,
  "authRejectWindowMinutes": 5,
  "flapThreshold": 4,
  "flapWindowMinutes": 2,
  "refusedCooldownMinutes": 60,
  "reconnectGracePeriodSeconds": 60,
  "availabilityDebounceSeconds": 5,
  "mail": {
    "enabled": false,
    "from": "CPADMIN <[email protected]>",
    "transport": {
      "host": "smtp.example.com",
      "port": 587,
      "secure": false,
      "auth": { "user": "...", "pass": "..." }
    }
  },
  "webpush": {
    "enabled": false,
    "vapidSubject": "mailto:[email protected]",
    "vapidPublicKey": "",
    "vapidPrivateKey": ""
  },
  "pushover": {
    "enabled": false
  }
}