Skip to content

Getting Started

Jump to bottom
Max Oesterle edited this page Jun 14, 2026 · 1 revision

Getting Started

This page explains how to set up the Vitruv-UI-Methodologist for local development. You will need both the frontend and the backend running. The backend requires PostgreSQL and Keycloak, which are started via Docker Compose.

Prerequisites

Tool Minimum version Notes
Node.js 18 LTS recommended
npm 9 Comes with Node
Docker Desktop any recent For PostgreSQL + Keycloak
Git any —
Java 17 17 For the backend only
Maven 3.9 For the backend only

1 — Start the backend services (Docker)

The backend repository contains a docker-compose.yml that starts PostgreSQL and Keycloak. From inside the methodologistUI-backend directory:

docker compose up -d

This starts:

  • PostgreSQL on port 3454
  • Keycloak on port 7668

Wait until both containers report healthy before continuing.

Windows note: Use PowerShell. If docker compose is not recognized, make sure Docker Desktop is running and the docker CLI is on your PATH.

2 — Start the backend

Still inside methodologistUI-backend, build and run the Spring Boot application:

mvn spring-boot:run

The backend starts on http://localhost:9811.

You can verify it is running by opening the Swagger UI:

http://localhost:9811/swagger-ui.html

Flyway will automatically apply any pending database migrations on startup.

3 — Set up the frontend

Clone the repository

git clone <frontend-repo-url>
cd Vitruv-UI-Methodologist

Install dependencies

npm install

Configure the environment

cp .env.example .env.local

The default .env.local points to the local backend — no changes needed unless your backend runs on a different port:

REACT_APP_API_BASE_URL=http://localhost:9811
REACT_APP_ENV=local

4 — Start the frontend

npm start

The development server starts on http://localhost:3000 and opens the app in your default browser automatically.

Hot-reload is enabled — saving a file in src/ will instantly update the running app without a full page refresh.

5 — Create an account

  1. Open http://localhost:3000
  2. Click Sign Up and fill in your details
  3. Check your email for the OTP verification code (valid for 5 minutes)
  4. Enter the code on the verification screen
  5. You are redirected to the Home screen

If you are a KIT member, you can use the KIT Login button on the sign-in screen to authenticate via Keycloak SSO instead.

Available npm scripts

Command What it does
npm start Dev server with hot-reload (uses .env.local)
npm test Runs the Jest / React Testing Library test suite
npm run build Production build (generic)
npm run build:staging Production build targeting the staging backend
npm run build:production Production build targeting the production backend

Environment files

File Used by Backend URL
.env.local npm start http://localhost:9811
.env.staging npm run build:staging BW-Cloud staging instance
.env.production npm run build:production Production instance

Only .env.example is committed to the repository. The actual .env.local, .env.staging, and .env.production files are gitignored and must be created locally or provided by the team.

Deployment (staging / production)

The built frontend is served by nginx. The docker/nginx.conf in the repository configures nginx to:

  • serve the React SPA from /usr/share/nginx/html on port 8082
  • proxy /api/ requests to the Spring Boot backend container (backend:8080)
  • proxy /realms/ requests to the Keycloak container (keycloak:8081)

To build and deploy to staging:

npm run build:staging
# Then copy the build/ output into the nginx container's html directory

Troubleshooting

REACT_APP_API_BASE_URL is not defined You are missing .env.local. Run cp .env.example .env.local and restart the dev server.

Login fails with "Network error" or CORS error The backend is not running or not reachable. Check that http://localhost:9811/swagger-ui.html is accessible.

OTP email is not arriving Check that the backend's mail configuration (SMTP settings in application.properties) is set up correctly. In some local setups a mailhog or similar local SMTP server is used — ask your team lead for the current configuration.

Docker containers not starting Make sure Docker Desktop is running. Check for port conflicts: PostgreSQL needs 3454 and Keycloak needs 7668 to be free.

Keycloak SSO (KIT Login) not working locally The KIT SSO redirect requires the callback URL to be registered in Keycloak. For local development, use username/password sign-in instead.

Clone this wiki locally