Getting Started

Getting Started

Prerequisites

• JDK 21
• Docker + Docker Compose (for PostgreSQL, Kafka, Keycloak, and running the stack)
• Go 1.25+ (only to build the device adapters)
• Node 20+ (only for the UI)

The Gradle wrapper is committed, so you don't need a local Gradle.

Build & test

./gradlew build          # compiles all Java services + runs tests (Testcontainers needs Docker)
./gradlew :services:inventory:test    # a single service's tests
cd services/adapters/conveyor && go build ./... && go test ./...   # a Go adapter

CI runs the same on every PR (GitHub Actions): Java build+test, Go adapter build/vet/test, UI build, and OpenAPI validation.

Run the stack (Docker Compose)

cd platform
docker compose --profile apps up --build

This brings up PostgreSQL, Kafka, Keycloak (imports the openwcs realm), every Java service, the Go adapters, and the gateway.

Ports

	Port		Port
gateway	8080	txlog	8086
master-data	8081	iam	8087
inventory	8082	notification	8088
process-engine	8083	integration-sap	8089
order-management	8084	integration-manhattan	8090
flow-orchestrator	8085	allocation	8091
integration-host	8092	conveyor/asrs/amr/autostore	9091–9094
ui	5173 dev, 80 prod	Keycloak	8180

Everything is reached through the gateway at /api/<service>/** (see API Reference).

Try demo mode (optional)

With the full stack running, sign in as admin / admIn1!, go to Settings → Demo mode, and switch it on. This seeds 100 sample SKUs (each with a base-unit + pack UoM and EAN-13 barcodes), outbound shippers, and a storage HU type — so you can explore the catalog, cubing and allocation flows without needing a connected WMS/ERP. Switch it off to remove everything it created. Demo mode is ADMIN-only and only available on a system with an empty catalog.

Enabling security (optional)

Off by default. To turn on JWT validation + RBAC, set OPENWCS_SECURITY_ENABLED=true and point the gateway at the realm — see Security.

Deploying for real

This page is the developer loop. To install and run openWCS on a local Linux server, a cloud VM, or as managed containers on AWS / Google Cloud / Azure, see the Deployment Guide.

Next

• Deployment Guide · Architecture · Services · Host Integration · Contributing