{"id":30755151,"url":"https://github.com/citrineos/citrineos-core","last_synced_at":"2026-02-06T21:02:44.255Z","repository":{"id":200992159,"uuid":"706394072","full_name":"citrineos/citrineos-core","owner":"citrineos","description":"Charging Station Management System based on OCPP 2.0.1","archived":false,"fork":false,"pushed_at":"2025-09-03T18:08:03.000Z","size":7955,"stargazers_count":175,"open_issues_count":5,"forks_count":87,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-09-03T19:42:47.657Z","etag":null,"topics":["charging-station-management-system","emobility","ocpp201","smarthome","typescript"],"latest_commit_sha":null,"homepage":"https://citrineos.github.io/","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/citrineos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-10-17T21:30:57.000Z","updated_at":"2025-09-03T06:07:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"7089f2fb-ad3c-43f1-9c91-920ddd70d9b7","html_url":"https://github.com/citrineos/citrineos-core","commit_stats":{"total_commits":69,"total_committers":4,"mean_commits":17.25,"dds":0.2028985507246377,"last_synced_commit":"93921b3ada1b1c4667fb965f1c97aee78d608695"},"previous_names":["citrineos/citrineos-core"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/citrineos/citrineos-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citrineos%2Fcitrineos-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citrineos%2Fcitrineos-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citrineos%2Fcitrineos-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citrineos%2Fcitrineos-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/citrineos","download_url":"https://codeload.github.com/citrineos/citrineos-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/citrineos%2Fcitrineos-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273588920,"owners_count":25132857,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["charging-station-management-system","emobility","ocpp201","smarthome","typescript"],"created_at":"2025-09-04T10:01:31.277Z","updated_at":"2026-02-06T21:02:44.248Z","avatar_url":"https://github.com/citrineos.png","language":"TypeScript","funding_links":[],"categories":["Tools and Resources"],"sub_categories":["OCPP"],"readme":"![CitrineOS Logo](logo_white.png#gh-dark-mode-only)\n![CitrineOS Logo](logo_black.png#gh-light-mode-only)\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"OCPP_201_Logo_core_and_advanced_security.png\" alt=\"CitrineOS Certification Logo\" width=\"200\" height=\"100\" /\u003e\n\u003c/div\u003e\n\n# Welcome to CitrineOS\n\nCitrineOS is an open-source project aimed at providing a modular server runtime for managing Electric Vehicle (EV)\ncharging infrastructure. This README will guide you through the process of installing and running CitrineOS.\n\nThis is the main part of CitrineOS containing the actual charging station management logic, OCPP message routing and all\nawait (await sequelize).sync(); // Use { force: true } for dropping and recreating tables\n\nAll other documentation and the issue tracking can be found in our main repository\nhere: \u003chttps://github.com/citrineos/citrineos\u003e.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Starting the Server without Docker](#starting-the-server-without-docker)\n- [Attaching Debugger](#attaching-debugger)\n- [Usage](#usage)\n- [Testing with EVerest](#testing-with-everest)\n- [Running clean and fresh](#running-clean-and-fresh)\n- [Linting and Prettier](#linting-and-prettier)\n- [Information on Docker setup](#information-on-docker-setup)\n- [Generating OCPP Interfaces](#generating-ocpp-interfaces)\n- [Validating custom OCPP DataTransfer messages](#data-transfer-messages)\n- [Hasura Metadata](#hasura-metadata)\n- [Database Sync vs. Migration](#database-sync-vs-migration)\n- [Contributing](#contributing)\n- [Licensing](#licensing)\n- [Support and contact](#support-and-contact)\n- [Roadmap](#roadmap)\n\n## Overview\n\nCitrineOS is developed in TypeScript and runs on `NodeJS` with [ws](https://github.com/websockets/ws)\nand [fastify](https://fastify.dev/).\n\nThe system features:\n\n- Dynamic OCPP 2.0.1 message schema validation, prior to transmission using `AJV`\n- Generated OpenAPIv3 specification for easy developer access\n- Configurable logical modules with decorators\n  - `@AsHandler` to handle incoming OCPP 2.0.1 messages\n  - `@AsMessageEndpoint` to expose functions allowing to send messages to charging stations\n  - `@AsDataEndpoint` to expose CRUD access to entities defined in `01_Data`\n- Utilities to connect and extend various message broker and cache mechanisms\n  - Currently supported brokers are `RabbitMQ` and `Kafka`\n  - Currently supported caches are `In Memory` and `Redis`\n\nFor more information on the project go to [citrineos.github.io](https://citrineos.github.io).\n\n### Prerequisites\n\nBefore you begin, make sure you have the following installed on your system:\n\n- Node.js (v22.11 or higher): [Download Node.js](https://nodejs.org/)\n- npm (Node Package Manager): [Download npm](https://www.npmjs.com/get-npm)\n- Docker (Optional). Version \u003e= 20.10: [Download Docker](https://docs.docker.com/get-docker/)\n\n### Installation\n\n1. Clone the CitrineOS repository to your local machine:\n\n   ```shell\n   git clone https://github.com/citrineos/citrineos-core\n   ```\n\n1. Install project dependencies from root dir:\n\n   ```shell\n   npm run install-all\n   ```\n\n1. Build project from root dir:\n\n   ```shell\n   npm run build\n   ```\n\n1. The docker container should be initialized from `cd /Server` by running `docker-compose -f ./docker-compose.yml up -d` or\n   by using the IntelliJ `Server` Run Configuration which was created for this purpose.\n\n1. Running `docker-compose.yml` will ensure that the container is configured to expose the `:9229` debugging\n   port for the underlying NodeJS process. A variety of tools can be utilized to establish a debugger connection\n   with the exposed localhost 9229 port which is forwarded to the NodeJS service running within docker. The IntelliJ\n   `Attach Debugger` Run Configuration was made to attach to a debugging session.\n\n### Database Sync vs. Migration\n\nBy default, CitrineOS uses migrations to manage database schema changes. This is the recommended approach for production environments.\n\nFor development purposes, you can also use `sync` to automatically synchronize your database schema with the models. There are two sync scripts available:\n\n- `npm run sync-db`: This will synchronize the database schema with the models without altering existing tables. This is useful for development when you want to quickly update the schema without losing data.\n- `npm run force-sync-db`: This will drop all tables and recreate them based on the models. This is useful when you want to start with a fresh database.\n\n**Disclaimer:** Using `sync` in a production environment is not recommended as it can lead to data loss. Always use migrations for production deployments.\n\n### Runtime configuration\n\nValues from configuration files (`local.ts`, `docker.ts`, `swarm.docker.ts`) may be overridden at runtime via environment variables. Environment variables prefixed with `citrineos_` and hierarchically separated by an underscore will result in overriding said value. For example, the amqp URL:\n\n```json\nutil: {\n    (...)\n    messageBroker: {\n        amqp: {\n            url: 'amqp://guest:guest@localhost:5672'\n            (...)\n        }\n        (...)\n    }\n    (...)\n}\n```\n\nmay be overridden by setting the environment variable `CITRINEOS_util_messageBroker_amqp_url` (case-insensitive).\n\n### Starting the Server without Docker\n\nCitrineOS requires configuration to allow your OCPP 2.0.1 compliant charging stations to connect.\n\nWe recommend running and developing the project with the `docker-compose` set-up via the existing Run Configurations.\nAdditional Run Configurations should be made for other IDEs (ex VSCode).\n\nTo change necessary configuration for execution outside of `docker-compose`, please adjust the configuration file\nat `Server/src/config/envs/local.ts`. Make sure any changes to the local configuration do not make it into your PR.\n\n## Starting the Server\n\nTo start the CitrineOS server, run the following command:\n\n```shell\ncd Server\nnpm run start\n```\n\nThis will launch the CitrineOS server with the specified configuration. The debugger will be available\non port 9229.\n\n### Attaching Debugger\n\nWhether you run the application with Docker or locally with npm, you should be able to attach a debugger.\nWith debugger attached you should be able to set breakpoints in the TS code right from your IDE and debug\nwith ease.\n\n## Attaching Debugger before execution using `--inspect-brk`\n\nYou can modify `nodemon.json` exec command from:\n\n```shell\nnpm run build --prefix ../ \u0026\u0026 node --inspect=0.0.0.0:9229 ./dist/index.js\n```\n\nto\n\n```shell\nnpm run build --prefix ../ \u0026\u0026 node --inspect-brk=0.0.0.0:9229 ./dist/index.js\n```\n\nwhich will wait for the debugger to attach before proceeding with execution.\n\n## Usage\n\nYou can now connect your OCPP 2.0.1 compliant charging stations to the CitrineOS server. Make sure to configure the\ncharging stations to point to the server's IP address and port as specified in the config.json file.\n\n## Testing with EVerest\n\nThis [README](./Server/everest/README.md)\n\n## Running `clean` and `fresh`\n\nOur current module structure consists of multiple `npm` submodules that are loaded as dependencies\nrunning the application. This results in the need to rebuild modules that have any file changes. In\nsome cases, in particular when switching between branches, especially when there are changes in the\npackage.json, the already built `dist` as well as the already generated `package-lock.json` may\nbecome invalid.\n\nTo alleviate the above, we created the `npm run fresh` and the `npm run clean` commands.\n\n`npm run fresh` - will delete all `node_modules`, `dist`, `tsbuildinfo`, `package-lock.json` and clear cache\n`npm run clean` - sub set of `npm run fresh` will only delete the build files `dist` and `tsbuildinfo`\n\n## Linting and Prettier\n\nEslint and Prettier have been configured to help support syntactical consistency throughout the codebase.\n\n`npm run prettier` - will run prettier and format the files\n`npm run lint` - will run linter\n`npm run lint-fix` - will run prettier and linter -fix flag which will attempt to resolve any linting issues.\n\n## Information on Docker setup\n\nYou need to install\n[docker](https://docs.docker.com/engine/install/#server) (\u003e= 20.10) and\n[docker-compose](https://docs.docker.com/compose/install/#install-compose).\nFurthermore, [Visual Studio\nCode](https://code.visualstudio.com/docs/setup/linux) might be handy as\na common integrated development environment.\n\n### ARM64 (Apple Silicon) Compatibility\n\nIf you're running on Apple Silicon Macs (ARM64 architecture), use the ARM64-compatible docker-compose file:\n\n```shell\ncd Server\ndocker-compose -f docker-compose.arm64.yml up -d\n```\n\nThe `docker-compose.arm64.yml` file includes platform specifications (`platform: linux/amd64`) and compatible image versions for:\n\n- RabbitMQ (uses version 3.12-management for better emulation compatibility)\n- PostGIS/PostgreSQL\n- MinIO and MinIO client\n- Hasura GraphQL Engine\n\n**Note:** The ARM64 version runs these services through x86_64 emulation, which may have slightly reduced performance but provides full compatibility.\n\nFor regular x86_64 systems, continue using the standard `docker-compose.yml`:\n\n```shell\ncd Server\ndocker-compose up -d\n```\n\nOnce Docker is running, the following services should be available:\n\n- **CitrineOS** (service name: citrineos) with ports\n  - `8080`: webserver http - [Swagger](http://localhost:8080/docs)\n  - `8081`: websocket server tcp connection without auth\n  - `8082`: websocket server tcp connection with basic http auth\n- **RabbitMQ Broker** (service name: amqp-broker) with ports\n  - `5672`: amqp tcp connection\n  - `15672`: RabbitMQ [management interface](http://localhost:15672)\n- **PostgreSQL** (service name: ocpp-db), PostgreSQL database for persistence\n  - `5432`: sql tcp connection\n- **Localstack** (service name: localstack) on port 4566 for mocking aws services\n  - `:4566`: unified AWS service endpoint\n\nThese three services are defined in `docker-compose.yml` and they\nlive inside the docker network `docker_default` with their respective\nports. By default these ports are directly accessible by using\n`localhost:8080` for example.\n\nSo, if you want to access the **amqp-broker** default management port via your\nlocalhost, you need to access `localhost:15672`.\n\n# Bootstrap Configuration Environment Variables\n\nAll environment variables use the `CITRINEOS_` prefix.\nAdditional prefixes can be added by passing the --env-prefix argument to nodemon (see \"start:instance1\" in Server/package.json)\nHere's the complete list of environment variables that are used in bootstrapping the application (this is not the full system configuration):\n\n## Basic Bootstrap Configuration\n\n- `BOOTSTRAP_CITRINEOS_CONFIG_FILENAME` - Name of the main config file (default: `config.json`)\n- `BOOTSTRAP_CITRINEOS_CONFIG_DIR` - Directory containing the config file (optional)\n- `BOOTSTRAP_CITRINEOS_FILE_ACCESS_TYPE` - Type of file access: `local`, `s3`, or `gcp`\n\n## Database Configuration\n\nDatabase connection details (moved from system config to bootstrap config for better security and 12-factor compliance):\n\n- `BOOTSTRAP_CITRINEOS_DATABASE_HOST` - Database host (default: `localhost`)\n- `BOOTSTRAP_CITRINEOS_DATABASE_PORT` - Database port (default: `5432`)\n- `BOOTSTRAP_CITRINEOS_DATABASE_NAME` - Database name (default: `citrine`)\n- `BOOTSTRAP_CITRINEOS_DATABASE_DIALECT` - Database dialect (default: `postgres`)\n- `BOOTSTRAP_CITRINEOS_DATABASE_USERNAME` - Database username (optional)\n- `BOOTSTRAP_CITRINEOS_DATABASE_PASSWORD` - Database password (optional)\n- `BOOTSTRAP_CITRINEOS_DATABASE_SYNC` - Enable database sync (via sequelize) (true/false, default: `false`)\n- `BOOTSTRAP_CITRINEOS_DATABASE_ALTER` - Enable database alter (via sequelize) (true/false, default: `false`)\n- `BOOTSTRAP_CITRINEOS_DATABASE_MAX_RETRIES` - Maximum connection retries (default: `3`)\n- `BOOTSTRAP_CITRINEOS_DATABASE_RETRY_DELAY` - Retry delay in milliseconds (default: `1000`)\n\n## Local File Access\n\nWhen `BOOTSTRAP_CITRINEOS_FILE_ACCESS_TYPE=local`:\n\n- `BOOTSTRAP_CITRINEOS_FILE_ACCESS_LOCAL_DEFAULT_FILE_PATH` - Default file path (default: `/data`)\n\n## S3 File Access\n\nWhen `BOOTSTRAP_CITRINEOS_FILE_ACCESS_TYPE=s3`:\n\n- `BOOTSTRAP_CITRINEOS_FILE_ACCESS_S3_REGION` - AWS region (optional)\n- `BOOTSTRAP_CITRINEOS_FILE_ACCESS_S3_ENDPOINT` - S3 endpoint URL (for MinIO or custom S3)\n- `BOOTSTRAP_CITRINEOS_FILE_ACCESS_S3_DEFAULT_BUCKET_NAME` - S3 bucket name (default: `citrineos-s3-bucket`)\n- `BOOTSTRAP_CITRINEOS_FILE_ACCESS_S3_FORCE_PATH_STYLE` - Force path style (true/false, default: `true`)\n- `BOOTSTRAP_CITRINEOS_FILE_ACCESS_S3_ACCESS_KEY_ID` - S3 access key ID\n- `BOOTSTRAP_CITRINEOS_FILE_ACCESS_S3_SECRET_ACCESS_KEY` - S3 secret access key\n\n## GCP File Access\n\nWhen `CITRINEOS_FILE_ACCESS_TYPE=gcp`:\n\n- `BOOTSTRAP_CITRINEOS_FILE_ACCESS_GCP_PROJECTID` - Project ID\n- `BOOTSTRAP_CITRINEOS_FILE_ACCESS_GCP_CREDENTIALS` - GCP Credentials object (Optional, if not set will use Application Default Credentials such as GOOGLE_APPLICATION_CREDENTIALS environment variable or gcloud CLI credentials)\n\n## Generating OCPP Interfaces\n\nAll CitrineOS interfaces for OCPP 2.0.1-defined schemas were procedurally generated using the script in\n00_Base/json-schema-processor.js.\nIt can be rerun:\n\n```shell\nnpm run generate-interfaces -- ../../Path/To/OCPP-2.0.1_part3_JSON_schemas\n```\n\nThis will replace all the files in `00_Base/src/ocpp/model/`.\nAs of release 1.8.0, the schema files used by CitrineOS are not the raw output of this function; we have added field-level validation that the official schemas lack.\n\n## Data Transfer Messages\n\nIt is possible to add custom JSON schemas to validate the data fields of DataTransfer messages, which are supported by all OCPP versions.\nIn the Server/index.ts code, there is a function ajvInstance() that creates the AJV instance. Here, you could register DataTransfer schemas:\n\n```\nimport { MyDataTransferRequestSchema } from './path'\n...\najvInstance.compile(MyDataTransferRequestSchema);\n```\n\nNote: The schema's `$id` field must follow this format:\n\n```\n${protocol}-${dataTransferRequest.vendorId}${dataTransferRequest.messageId ? `-${dataTransferRequest.messageId}` : ''}\n```\n\n'Protocol' is the OCPP websocket subprotocol, i.e. \"ocpp1.6\", \"ocpp2.0.1\", or so on.\n\nCitrineOS's validation logic assumes that the data field is a string field with JSON structure, and uses JSON.parse before validation. Other approaches to custom DataTransfer message types are not supported.\n\n## Hasura Metadata\n\nIn order for Hasura to track the existing Citrine tables and relationships, this repository comes with Hasura metadata already exported into the `hasura-metadata` folder.\nRunning the Docker container will automatically import this metadata and track all tables and relationships.\n\nUnfortunately, Hasura doesn't currently support importing metadata from a JSON (which is the format if you export your metadata from the Hasura UI or API).\nRefer to this issue for more information: https://github.com/hasura/graphql-engine/issues/8423#issuecomment-1115996153.\n\nTherefore, you must use the Hasura CLI to re-export your metadata, should something change with it. As explained in the Hasura docs https://hasura.io/docs/2.0/migrations-metadata-seeds/auto-apply-migrations/#auto-apply-metadata,\nHasura provides an image called `hasura/graphql-engine:\u003cversion\u003e.cli-migrations-v3` that will process and import the metadata first before starting the server and\nruns the Hasura CLI internally. This is the image CitrineOS normally uses in order to automatically load accurate metadata. However, if you want to capture the current state of your database, you should use a normal version tag (such as `v2.40.3` instead of `v2.40.3.cli-migrations-v3`). Then proceed to the hasura console at `localhost:8090`, go to the data tab, use the sidebar to navigate to the database schema at default\u003epublic, and track all of the tables, relationships, and functions you need. Then proceed with the below instructions.\n\nYou can follow these steps to re-export your metadata via the Hasura CLI in the `graphql-engine` container:\n\n- (if the hasura cli isn't installed):\n\n```\ncurl -L https://github.com/hasura/graphql-engine/raw/stable/cli/get.sh | bash\n```\n\n- (If not yet initialized) Initialize the Hasura project in the `graphql-engine` container (you can do this via the Docker Desktop `exec` view):\n\n```\nhasura-cli init\nOR\nhasura init\n\nenter any name you wish for the project (i.e. citrine)\n```\n\n- Export the metadata by executing this command in `graphql-engine` container:\n\n```\nhasura-cli metadata export\nOR\nhasura metadata export\n```\n\n- Find the exported files in the `graphql-engine` container's files in the metadata filepath `\u003cname of project i.e. citrine\u003e/metadata` and pull that metadata backup onto your local machine\n- Copy the contents of the copied `metadata` folder into the `hasura-metadata` folder in this repository\n\n## Contributing\n\nWe welcome contributions from the community. If you would like to contribute to CitrineOS, please follow\nour [contribution guidelines](https://github.com/citrineos/citrineos/blob/main/CONTRIBUTING.md).\n\n## Licensing\n\nCitrineOS and its subprojects are licensed under the Apache License, Version 2.0. See LICENSE for the full license text.\n\n## Support and Contact\n\nIf you have any questions or need assistance, feel free to reach out to us on our community forum or create an issue on\nthe GitHub repository.\n\n## Roadmap\n\n[Roadmap](https://citrineos.github.io/docs/roadmap.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcitrineos%2Fcitrineos-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcitrineos%2Fcitrineos-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcitrineos%2Fcitrineos-core/lists"}