Welcome to the Community Edition of OpenEPCIS — an open-source, container-friendly implementation of the GS1 EPCIS 2.0 standard. This project provides a modern foundation for deploying, developing, or extending EPCIS repositories in line with GS1 visibility standards.
✅ Optimized for JSON-LD, RESTful APIs, and real-time event capture
🧪 Includes both stable (Community) and experimental (Research) editions
🔧 Built on Kafka, Quarkus, OpenSearch, and container-native tooling
- What is EPCIS 2.0?
- What is OpenEPCIS?
- Repository Structure
- Getting Started
- Ready to Try Event Capture?
- Sample Requests
- Dashboards
- Learn More
- Contributing
- License
EPCIS (Electronic Product Code Information Services) is a GS1 standard for sharing supply chain event data. Version 2.0 introduces major improvements:
- ✅ Native JSON/JSON-LD support
- 🌐 Better interoperability with web services
- 📡 Event-based RESTful communication
- 🔁 Enhanced modeling for serialized products, sensor data, and IoT
- 🔗 Seamless integration with GS1 Digital Link
OpenEPCIS is a modular, scalable EPCIS 2.0 repository built for production and experimentation.
- Fast, reactive architecture using Quarkus
- Kafka-powered event pipelines
- Built-in OpenSearch integration for queries
- RESTful API supporting EPCIS 2.0 (JSON-LD)
- Native support for custom extension schemas
- Runs with Docker, Podman, or as a native Java app
distributions/
├── community-edition/ # REST API (Community Edition)
├── research-edition/ # REST API (Research Edition)
docker/
├── docker-compose.yml # Infra stack (Kafka, OpenSearch, Dashboards)
├── .env # Environment variables
modules/
├── openepcis-rest-api-common/ # Shared API components
├── openepcis-client/ # REST/WebSocket client
├── openepcis-generated-events-capture/ # Synthetic test data generator
├── quarkus-capture-topology-ce/ # Kafka capture stream (CE)
├── quarkus-rest-application-ce/ # Community Edition entrypoint
To launch the minimal OpenEPCIS stack locally:
- Clone the repository
- Navigate to the
dockerdirectory - Start the services using Docker Compose
git clone https://github.com/openepcis/epcis-repository-ce.git
cd epcis-repository-ce/dockerFor details on what services are included and how to configure them, refer to the docker/README.md.
Best for pure open-source environments.
Prerequisites:
When running on MacOS or Windows make sure to setup your Podman VM Resources - we need a bit more... But you don't need to set rootless!
# Create VM for 8GB of memory and 8 CPUs
podman machine init --memory=8192 --cpus=8
# and start it
podman machine startStart Community Edition REST API:
podman-compose -f docker-compose.yml -f docker-compose.rest-api-ce.yml up -d
# Run one-time Kafka topic setup
podman-compose -f docker-compose.kafka-setup.yml run --rm kafkasetup
# Restart REST API to pick up topics
podman restart quarkus-rest-api-ce
# check logs
podman logs --tail 250 -f quarkus-rest-api-ceOr Research Edition
podman-compose -f docker-compose.yml -f docker-compose.rest-api-re.yml up -d
# Run one-time Kafka topic setup
podman-compose -f docker-compose.kafka-setup.yml run --rm kafkasetup
# Restart REST API to pick up topics
podman restart quarkus-rest-api-re
# check logs
podman logs --tail 250 -f quarkus-rest-api-reStart Community Edition REST API:
docker compose -f docker-compose.rest-api-ce.yml up -d
# Run one-time Kafka topic setup
docker compose -f docker-compose.kafka-setup.yml run --rm kafkasetup
# Restart REST API to pick up topics
podman restart quarkus-rest-api-ce
# check logs
docker logs --tail 250 -f quarkus-rest-api-ceOr Research Edition
docker compose -f docker-compose.rest-api-re.yml up -d
# Run one-time Kafka topic setup
docker compose -f docker-compose.kafka-setup.yml run --rm kafkasetup
# Restart REST API to pick up topics
podman restart quarkus-rest-api-re
# check logs
docker logs --tail 250 -f quarkus-rest-api-reRun locally using Maven + hot reload.
Prerequisites:
- Java 21+
- Apache Maven
- Docker or Podman (for dependencies)
docker compose up -d
docker compose --profile init run --rm kafkasetup
cd distributions/community-edition
mvn quarkus:devTake a look at the full capture walkthrough to learn how to:
- Register extension schemas for custom EPCIS fields
- Send test events using
curlor the built-in generator - Verify captured data in OpenSearch and Dashboards
It’s the fastest way to see OpenEPCIS in action.
Use curl to test the capture endpoint:
curl -X POST http://localhost:8080/capture \
-H "Content-Type: application/json" \
-d @modules/openepcis-generated-events-capture/src/test/resources/epcisEvent.jsonQuery captured events:
curl http://localhost:8080/eventsOpenEPCIS uses OpenSearch for indexing and provides tools for visual traceability.
Visit: http://localhost:5601
- Filter and inspect raw event data
- Monitor by business step, disposition, product
- Build custom charts and dashboards
Dashboards are not shipped by default — you can build them using
epcis-event*indices.
You can connect Grafana to OpenSearch:
- Use OpenSearch plugin or native support
- Combine EPCIS with other telemetry data
- Build alerts or cross-supply chain views
- GS1 EPCIS 2.0 Standard
- GS1 Core Business Vocabulary (CBV)
- GS1 Digital Link
- Quarkus
- Apache Kafka
- OpenSearch
- OpenEPCIS Tools
- Event Sentry Validator
We welcome your feedback and contributions.
- Fork and submit a PR
- Open issues for bugs or enhancements
- Join discussions in GitHub
The OpenEPCIS Community Edition is licensed under the Apache 2.0 License.
⚠️ Note: The Research Edition includes a SAX-based XML converter and other components distributed under a separate license by benelog GmbH & Co. KG. Commercial usage of these components requires a separate agreement. Contact: [email protected]