Running OCPI
Before continuing, set up the necessary prerequisites and get CitrineOS running.
Running with Docker#
In the repository root, you can execute one of the following commands to spin up a complete CitrineOS environment in Docker:
pnpm citrine --ocpi # ocpp-server + operator UI + ocpi-server from published ghcr.io images
pnpm citrine --local --ocpi # ocpp-server + operator UI + ocpi-server from local source instead of pulling
Once running, OCPI is accessible at localhost:8085 with Swagger UI docs available at localhost:8085/docs.
Stopping Docker#
If you want to take down the containers:
pnpm citrine down --ocpi # stop the stack (pass the same flags you started it with)
Setting up a Tenant Partner#
CitrineOS OCPP and OCPI will see each other via a Tenant Partner, which you can set up via the Operator UI or via the sample GraphQL below (ensure CitrineOS is running):
mutation UpsertDefaultTenantPartner() {
insert_TenantPartners_one(
object: {
id: 1
tenantId: 1
partyId: "TST"
countryCode: "US"
createdAt: "2026-08-07T17:55:00+00:00"
updatedAt: "2026-09-21T00:00:00.000Z"
partnerProfileOCPI: {
"roles": [
{
"role": "EMSP",
"businessDetails": {
"logo": {
"url": "https://www.test-mobility.com/assets/brand/logo.svg",
"type": "svg",
"width": 150,
"height": 60,
"category": "OPERATOR"
},
"name": "TestMobilitySolutions",
"website": "https://www.test-mobility.com"
}
}
],
"version": {
"version": "2.2.1",
"versionDetailsUrl": "http://host.docker.internal:8083/ocpi/versions/2.2.1"
},
"endpoints": [
{ "url": "http://host.docker.internal:8083/ocpi/2.2.1/credentials", "identifier": "credentials" },
{ "url": "http://host.docker.internal:8083/ocpi/2.2.1/emsp/locations", "identifier": "locations_RECEIVER" },
{ "url": "http://host.docker.internal:8083/ocpi/2.2.1/emsp/tariffs", "identifier": "tariffs_RECEIVER" },
{ "url": "http://host.docker.internal:8083/ocpi/2.2.1/emsp/sessions", "identifier": "sessions_RECEIVER" },
{ "url": "http://host.docker.internal:8083/ocpi/2.2.1/emsp/cdrs", "identifier": "cdrs_RECEIVER" },
{ "url": "http://host.docker.internal:8083/ocpi/2.2.1/emsp/tokens", "identifier": "tokens_SENDER" },
{ "url": "http://host.docker.internal:8083/ocpi/2.2.1/emsp/commands", "identifier": "commands_SENDER" },
{ "url": "http://host.docker.internal:8083/ocpi/2.2.1/emsp/chargingprofiles", "identifier": "chargingprofiles_RECEIVER" }
],
"credentials": {
"token": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567",
"versionsUrl": "https://our-server.citrineos.com/ocpi/versions"
},
"serverCredentials": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9eyJzdWIiOiJwYXJ0bmVyIn0",
"versionsUrl": "http://host.docker.internal:8083/ocpi/versions"
}
}
}
on_conflict: {
constraint: TenantPartners_pkey
update_columns: [tenantId, partyId, countryCode, partnerProfileOCPI, updatedAt]
}
) {
id
tenantId
partyId
countryCode
createdAt
updatedAt
partnerProfileOCPI
}
}
Configuration#
| Config path | Type | Env var (as coded) | local.ts | docker.ts | Req. |
|---|---|---|---|---|---|
env |
'development' \| 'production' |
— | development |
development |
✅ |
ocpiServer.host |
string | — | 0.0.0.0 |
0.0.0.0 |
opt |
ocpiServer.port |
int > 0 | — | 8085 |
8085 |
opt |
ocpiModules.credentials.endpointPrefix |
string | — | /credentials |
/credentials |
opt |
ocpiModules.versions.endpointPrefix |
string | — | /versions |
/versions |
opt |
ocpiModules.locations.endpointPrefix |
string | — | /locations |
/locations |
opt |
ocpiModules.sessions.endpointPrefix |
string | — | /sessions |
/sessions |
opt |
ocpiModules.cdrs.endpointPrefix |
string | — | /cdrs |
/cdrs |
opt |
ocpiModules.tokens.endpointPrefix |
string | — | /tokens |
/tokens |
opt |
ocpiModules.tariffs.endpointPrefix |
string | — | /tariffs |
/tariffs |
opt |
ocpiModules.chargingProfiles.endpointPrefix |
string | — | /chargingprofiles |
/chargingprofiles |
opt |
ocpiModules.commands.endpointPrefix |
string | — | /commands |
/commands |
opt |
database.host |
string | DB_HOST |
localhost |
postgres |
opt |
database.port |
int > 0 | DB_PORT |
5432 |
5432 |
opt |
database.database |
string | DB_NAME |
citrine |
citrine |
opt |
database.username |
string | DB_USER |
citrine |
citrine |
opt |
database.password |
string | DB_PASS |
citrine |
citrine |
opt |
cache.memory |
boolean | — | true |
true if no REDIS_HOST |
⚠️ one of |
cache.redis.host |
string | REDIS_HOST |
— | set if present | ⚠️ one of |
cache.redis.port |
int > 0 | REDIS_PORT |
— | 6379 |
opt |
graphql.endpoint |
string | GRAPHQL_ENDPOINT |
http://localhost:8090/v1/graphql |
http://graphql-engine:8080/v1/graphql |
✅ |
graphql.headers |
Record<string,string> |
— | unused | unused | opt |
commands.timeout |
int > 0 (sec) | COMMANDS_TIMEOUT |
30 |
30 |
opt |
commands.ocpiBaseUrl |
string | COMMANDS_OCPI_BASE_URL |
http://localhost:8085/ocpi |
http://citrineos-ocpi:8085/ocpi |
opt |
commands.coreHeaders |
Record<string,string> (JSON) |
COMMANDS_CORE_HEADERS |
{} |
{} |
opt |
commands.ocpp1_6.remoteStartTransactionRequestUrl |
string | COMMANDS_OCPP1_6_REMOTE_START_TRANSACTION_REQUEST_URL |
http://localhost:8080/ocpp/1.6/evdriver/remoteStartTransaction |
http://citrine:8080/ocpp/1.6/evdriver/remoteStartTransaction |
✅ |
commands.ocpp1_6.remoteStopTransactionRequestUrl |
string | COMMANDS_OCPP1_6_REMOTE_STOP_TRANSACTION_REQUEST_URL |
http://localhost:8080/ocpp/1.6/evdriver/remoteStopTransaction |
http://citrine:8080/ocpp/1.6/evdriver/remoteStopTransaction |
✅ |
commands.ocpp1_6.unlockConnectorRequestUrl |
string | COMMANDS_OCPP1_6_UNLOCK_CONNECTOR_REQUEST_URL |
http://localhost:8080/ocpp/1.6/evdriver/unlockConnector |
http://citrine:8080/ocpp/1.6/evdriver/unlockConnector |
✅ |
commands.ocpp2_0_1.requestStartTransactionRequestUrl |
string | COMMANDS_OCPP2_0_1_REQUEST_START_TRANSACTION_REQUEST_URL |
http://localhost:8080/ocpp/2.0.1/evdriver/requestStartTransaction |
http://citrine:8080/ocpp/2.0.1/evdriver/requestStartTransaction |
✅ |
commands.ocpp2_0_1.requestStopTransactionRequestUrl |
string | COMMANDS_OCPP2_0_1_REQUEST_STOP_TRANSACTION_REQUEST_URL |
http://localhost:8080/ocpp/2.0.1/evdriver/requestStopTransaction |
http://citrine:8080/ocpp/2.0.1/evdriver/requestStopTransaction |
✅ |
commands.ocpp2_0_1.unlockConnectorRequestUrl |
string | COMMANDS_OCPP2_0_1_UNLOCK_CONNECTOR_REQUEST_URL |
http://localhost:8080/ocpp/2.0.1/evdriver/unlockConnector |
http://citrine:8080/ocpp/2.0.1/evdriver/unlockConnector |
✅ |
commands.ocpp2_1.requestStartTransactionRequestUrl |
string | COMMANDS_OCPP2_1_REQUEST_START_TRANSACTION_REQUEST_URL |
http://localhost:8080/ocpp/2.1/evdriver/requestStartTransaction |
http://citrine:8080/ocpp/2.1/evdriver/requestStartTransaction |
✅ |
commands.ocpp2_1.requestStopTransactionRequestUrl |
string | COMMANDS_OCPP2_1_REQUEST_STOP_TRANSACTION_REQUEST_URL |
http://localhost:8080/ocpp/2.1/evdriver/requestStopTransaction |
http://citrine:8080/ocpp/2.1/evdriver/requestStopTransaction |
✅ |
commands.ocpp2_1.unlockConnectorRequestUrl |
string | COMMANDS_OCPP2_1_UNLOCK_CONNECTOR_REQUEST_URL |
http://localhost:8080/ocpp/2.1/evdriver/unlockConnector |
http://citrine:8080/ocpp/2.1/evdriver/unlockConnector |
✅ |
messageBroker.amqp.url |
string | AMQP_URL |
amqp://guest:guest@localhost:5672 |
amqp://guest:guest@rabbitmq:5672 |
opt |
messageBroker.amqp.exchange |
string | AMQP_EXCHANGE |
ocpi |
ocpi |
opt |
messageBroker.kafka.brokers |
string[] | — | unused | unused | opt |
messageBroker.kafka.topicPrefix |
string | — | unused | unused | opt |
messageBroker.kafka.topicName |
string | — | unused | unused | opt |
messageBroker.kafka.sasl |
{mechanism, username, password} |
— | unused | unused | opt |
swagger.path |
string | — | unused (/docs) |
unused | opt |
swagger.logoPath |
string | — | unused | unused | ✅ if swagger set |
swagger.exposeData |
boolean | — | unused (true) |
unused | opt |
swagger.exposeMessage |
boolean | — | unused (true) |
unused | opt |
oidc.jwksUri |
string | — | unused | unused | ✅ if oidc set |
oidc.issuer |
string | — | unused | unused | ✅ if oidc set |
oidc.audience |
string | — | unused | unused | opt |
oidc.cacheTime |
number | — | unused | unused | opt |
oidc.rateLimit |
boolean | — | unused | unused | opt |
logLevel |
number 0–6 | LOG_LEVEL |
2 |
2 |
opt |
logRedaction.keys |
string[] | — | unused (['password']) |
unused | opt |
logRedaction.paths |
string[] | — | unused ([]) |
unused | opt |
logRedaction.patterns |
string[] (regex) | — | unused ([]) |
unused | opt |
logRedaction.placeholder |
string | — | unused ([***]) |
unused | opt |
logRedaction.redactKeyCodes |
boolean | — | unused (true) |
unused | opt |
defaultPageLimit |
int > 0 | DEFAULT_PAGE_LIMIT (docker only) |
50 hardcoded |
50 |
opt |
maxPageLimit |
int > 0 | MAX_PAGE_LIMIT (docker only) |
1000 hardcoded |
1000 |
opt |