Skip to main content

Step by step for local development setup 🛠️

📋 Prerequisites​

  • Docker and Docker Compose (v2) installed.
  • That's it for the default path — images are pulled from the public GHCR registry.
  • Only if you intend to build from source: Java 21 + Maven, and Node.js + Yarn. The Docker builds are multi-stage, so these are not required just to run the platform.

Step 1: Clone and configure 📥​

git clone https://github.com/wkspower/wks-platform.git
cd wks-platform
cp .env-sample .env

The defaults in .env target localhost and work out of the box.

Step 2: Start the platform 🚀​

Default (recommended) — pulls pre-built images, no build​

docker compose up -d

This starts the core backend, the case portal, and the one-shot demo-data-loader (the portal and demo profiles are enabled by default in .env). First start pulls images and may take a few minutes; the loader bootstraps the Keycloak realm + demo user and seeds sample cases. Wait for docker compose ps -a to show demo-data-loader as Exited (0), then log into http://localhost:3001 with demo / demo.

Without seeding​

COMPOSE_PROFILES=portal docker compose up -d

Starts the portal and backend but skips the loader — you'll need to provision the Keycloak realm/user yourself before you can log in.

With notifications (Kafka + email/websocket/Novu)​

KAFKA_ENABLED=true docker compose --profile portal --profile notifications up -d

Build from source instead of pulling​

docker compose up -d --build

The multi-stage Dockerfiles compile the Java/Node apps inside Docker — no host mvn/yarn step needed.

Step 3 (optional): Custom domain​

Skip this if you only use localhost. Otherwise copy/adjust values in .env (KEYCLOAK_TOKEN_URL, REACT_APP_*, MINIO_HOST_EXTERNAL, WEBSOCKET_URL, the Novu keys, and the default usernames/passwords) to match your domain, then bring the stack up.

Step 4: Service configuration​

If you changed the domain, update the wks-portal Keycloak client's Web origins and Valid redirect URIs to match. For a plain localhost setup the defaults already work.