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)
- gopass - a tool to sync secrets
- Node.js - JavaScript runtime & dependency management
- nodenv - manages the node.js environment
Backend only:
- java - we use Java 17 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)"
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
For shared secrets required for development we're using gopass
. To set up follow these steps:
Provide some team member a public GPG key with encryption capability (that team member will add you as a recipient).
Then, run:
gopass --yes setup --remote git@github.com:digitalservicebund/neuris-password-store.git --alias neuris --name <your-name-from-gpg-key> --email <your-email-from-gpg-key>
Note
If there are any issues with this command, you need to clean the store and try again until it works unfortunately
☹️ :rm -rf ~/.local/share/gopass/stores
Try if you can get access:
gopass ls
Synchronize the password store:
gopass sync
Now you can generate a new .env
file containig the secrets:
./run.sh env
Note
This needs to be repeated every time the secrets change.
The caselaw application requires the initialization of lookup tables by the migration application.
Follow the steps in run_migration_locally.md
WIP: Run docker image in migration_image.md
./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
To run a service separately:
./run.sh dev --no-backend
The application is available at http://127.0.0.1.
This will start the backend utilizing Spring Boot developer tools so changes in the Java sources will be reflected without manually restarting. Similarly, the frontend is served from Vite with HMR.
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
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:
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
To access the api documentation, start the application and navigate to /api/docs.html
or /api/docs.json
in your
browser.
Architecture decisions are kept in the doc/adr directory and are managed with adr-tools.
Opt in to CI posting notifications for failing jobs to a particular Slack channel by setting a
repository secret
with the name SLACK_WEBHOOK_URL
, containing a url
for Incoming Webhooks.
All reports will be published here https://digitalservicebund.github.io/ris-reports/