visualregressiontracker/api repository overview

⁠Backend app for Visual Regression Tracker⁠

⁠Local setup

• Install Node 18 (LTS)
• clone repo
• Update .env and prisma/.env
• Make sure Postgres is up and running, using docker compose up in a separate terminal
• npm i
• npm run test
• Create DB structure npx prisma db push
• Apply migrations npx prisma migrate deploy
• npm run test:e2e
• Seed initial data npx prisma db seed
• npm run start:debug

⁠Scaling to multiple instances (real-time updates)

Real-time UI updates are delivered over socket.io. Running more than one API instance requires both of the following — with only one, live updates break:

1. Redis backplane — set REDIS_URL so every instance shares a socket.io pub/sub adapter. Without it, an event emitted on one instance never reaches clients connected to another (events are silently lost and the UI only updates after a manual refresh).

   REDIS_URL=redis://<host>:6379
   

   Copy

   When REDIS_URL is unset, the default in-memory adapter is used, so a single instance and local development work with no extra setup.

2. Reverse proxy with sticky sessions + WebSocket upgrade for /socket.io/. Without sticky sessions the polling handshake fails with 400 "Session ID unknown" because consecutive requests land on different instances. Example nginx:

   map $http_upgrade $connection_upgrade { default upgrade; '' close; }
   
   upstream vrt_api {
     ip_hash;                 # sticky sessions
     server api_1:3000;
     server api_2:3000;
   }
   
   location /socket.io/ {
     proxy_pass http://vrt_api;
     proxy_http_version 1.1;
     proxy_set_header Upgrade $http_upgrade;
     proxy_set_header Connection $connection_upgrade;
     proxy_set_header Host $host;
     proxy_read_timeout 3600s;
   }
   

   Copy

Confirmed with a 4-replica deployment: nginx ip_hash + WebSocket upgrade fixes the handshake, but cross-replica event delivery still requires REDIS_URL.

⁠Local HTTPS config

• Generate keys here⁠
• place in folder /secrets named ssl.cert and ssl.key

⁠Local LDAP test server

• Run docker compose -f docker-compose.yml -f docker-compose.ldap.yml (see docker docs for multiple-compose-files - merge⁠)
• test the login with ldap and have a look at the logs

  curl 'http://localhost:4200/users/login' \
  -H 'accept: */*' \
  -H 'accept-language: de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7,fr;q=0.6' \
  -H 'content-type: application/json' \
  --data-raw '{"email":"[email protected]","password":"password"}'
  

  Copy

⁠OIDC (SSO)

Set OIDC_ENABLED=true and the OIDC_* variables in .env. Password login and registration are disabled while OIDC is enabled.

• Roles come from the identity provider. On every login the role is derived from OIDC_ROLE_CLAIM: admin when a value matches OIDC_ADMIN_VALUES, otherwise OIDC_DEFAULT_ROLE. Roles assigned in the VRT UI are overwritten at the next login. When the claim is missing from the token, an existing user keeps their role.
• OIDC_ROLE_CLAIM accepts a claim name or a dotted path into nested claims, e.g. realm_access.roles for Keycloak realm roles.
• Accounts are matched by email. The first login creates the user, later logins find them by the email claim. If a user's email changes at the identity provider, a new VRT account is created. Unverified emails are rejected unless OIDC_REQUIRE_VERIFIED_EMAIL=false.

⁠Local OIDC test server

• Run docker compose -f docker-compose.yml -f docker-compose.oidc.yml up (see docker docs for multiple-compose-files - merge⁠)
• The issuer (host.docker.internal:8090) must be reachable from both the api container and the browser. On macOS/Windows Docker Desktop this works out of the box; on Linux add 127.0.0.1 host.docker.internal to /etc/hosts.
• Open http://localhost:8080/login and click Login with SSO (or set REACT_APP_OIDC_AUTO_REDIRECT=true to redirect straight away).
• Mock users: username admin (role admin), any other username (role editor). The password is ignored. See oauth2-mock-server-config.json.
• Optional: inspect/trigger the flow manually via the debugger at http://host.docker.internal:8090/default/debugger.
• Verify the OIDC endpoints (api must run with OIDC enabled) and run the integration tests:

  curl -i 'http://localhost:4200/users/oidc/enabled'
  curl -i 'http://localhost:4200/users/oidc/login'
  npm run test:oidc
  

  Copy