Getting Started

Getting Started

Just want to explore? A hosted live demo runs at app.openwcs.ai — no install required. Enable Settings → Demo mode once signed in to seed sample stock and orders.

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! and set up storage locations for your warehouse (Master data → Locations), then go to Settings → Demo mode and switch it on. This seeds 100 movie-merch–named SKUs (Star Wars, Harry Potter, Marvel — each with EAN-13 barcodes), outbound shippers, a storage HU type, and — via the inventory service — DEMO-HU-### handling units with AVAILABLE stock placed into your existing locations. You get a fully populated Handling unit registry and Stock overview to explore immediately, without a connected WMS/ERP. Switching it off performs a full operational reset: all stock, reservations, handling units, orders, counts, transports, and GTP work for the warehouse are purged across services — infrastructure (warehouses, locations, topology, GTP/station config, equipment, users) is kept. Demo mode is ADMIN-only, requires an empty catalog, and requires storage locations to exist first.

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