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 storage locations (purpose=STORAGE) — never onto conveyors, stations, or other operational locations — plus 50 empty handling units (no stock) so the empty-HU flows — ASRS empty-HU management, GTP order totes — have totes to work with. 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 in two ordered phases: transport producers (flow, GTP, counting, orders) are torn down first so no in-flight transport callback can re-book a tote's location while the registry is being cleared, then the inventory registry and transaction journal are wiped, then the whole SKU catalog and demo shippers are removed from master data. All stock, reservations, handling units, orders, transports, counts, GTP work, the transaction journal, and the whole SKU catalog are purged — 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