RIS Caselaw

Prerequisites

You need (or may want) the following CLI tools. For UNIX users, there is a prepared Brewfile, see below.

Necessary tools:

• lefthook - manages our git hooks
• GitHub CLI - used by lefthook to check for pipeline status before push
• docker - our container runtime (on macOS, the easiest way is to use Docker Desktop)
• 1Password CLI - to access secrets
• Node.js - JavaScript runtime & dependency management
• nodenv - manages the node.js environment

Backend only:

• java - we use Java 21 in the backend

Optional, but recommended tools:

• jq - handy JSON Processor
• yq - handy YAML Processor
• actionlint - a tool that lints GitHub Action pipeline definitions
• shellcheck - shell script analyzer, that also provides extensions for VS Code
• trivy - our vulnerability scanner
• adr-tools - a command-line tool to manage our Architecture Decision Records (ADRs)
• direnv - manages our local environment

If you use homebrew, you can simply execute this to to install all required and optional dependencies:

brew bundle

If you decided to install direnv, you have to hook it onto your shell as described here. E.g. for ZSH add this to ~/.zshrc:

eval "$(direnv hook zsh)"

S3 Credentials for Lookup Table Initialization

The lookup table initialization in your local environment will be performed with data provided by a s3 bucket. Read here on how to retrieve credentials for it.

Then, store the credentials in 1Password:

op item create --category login --title 'NeuRIS S3' \
'access-key-id=<your-access-key-id>' \
'secret-access-key=<your-secret-access-key>'

Getting started

To get started with development, run:

./run.sh init

This will install a couple of Git hooks which are supposed to help you to:

• commit properly formatted source code only (and not break the build otherwise)
• write conventional commit messages
• not accidentally push on a failing pipeline

Also, it creates a new .env file containing the secrets. You will be asked to authorize requests to 1Password.

Note

This needs to be repeated every time the secrets change.

Lookup Tables Initialization

The caselaw application requires the initialization of lookup tables by the migration application image.

The following command will migrate the minimally required data (refdata and juris tables):

Make sure the latest ris data migration image is in compose.yaml and then run:

./run.sh dev -i

Note: If you wish to migrate documentation units, use the instructions in run_migration_locally.md

Development

Run the whole stack including migration (initialization) inside docker:

./run.sh dev

If you don’t want to watch the log stream but let Docker perform health checks until everything is up, use detached mode:

./run.sh dev -d
./run.sh dev --detached

To run the frontend stack only (without backend and initialization) run:

./run.sh dev -n
./run.sh dev --no-backend

To run the only required stack setup (without frontend and frontend) run:

./run.sh dev -n -f
./run.sh dev --no-backend --no-frontend

When choosing the no-backend variant, checkout the backend manual on how to run the backend stand-alone without docker. The easiest way would be to start the backend utilizing Spring Boot developer tools so changes in the Java sources will be reflected without manually restarting:

cd backend
SPRING_PROFILES_ACTIVE=local ./gradlew bootRun

Note: Similarly, the frontend is served from Vite with HMR

Overall docker compose spins up a reverse proxy (traefik) which listens on port 80. Therefore the application is available at http://127.0.0.1. If you get a bad gateway error make sure your firewall is not messing with you. On Ubuntu sudo ufw disable might do the trick. You may setup a certain firewall rule. Overall your milage may vary.

Note

When first starting the development server, dependencies will be installed automatically. This includes supported browsers for E2E and a11y testing through playwright. Should that fail, you can install them manually.

To see logs of the containers, use e.g.

docker compose logs # for all
docker compose logs frontend # for specific services

To stop the whole environment:

./run.sh down

Read the component individual documentation to figure out how to run them individually:

• backend
• frontend

Deployment

The pipeline performs the deployment through GitOps using ArgoCD ( see example pipeline deploy step definition):

• Build and push the new Docker image (see here)
• Commit the new tag in the deployment manifest in the neuris-infra repository
• Sync the respective ArgoCD App, which will cause ArgoCD to apply all changed Kubernetes manifests on the cluster to create the desired state

Tests

You can run both frontend and backend tests simultaneously with the following commit:

lefthook run tests

API Documentation

To access the api documentation, start the application and navigate to /api/docs.html or /api/docs.json in your browser.

Architecture Decision Records

Architecture decisions are kept in the doc/adr directory and are managed with adr-tools.

Slack notifications

Opt in to CI posting notifications for failing jobs to a particular Slack channel by using the org-secret with the name SLACK_BOT_TOKEN and setting the SLACK_CHANNEL_ID.

Reports

All reports will be published here https://digitalservicebund.github.io/ris-reports/