Skip to main content

Quick setup guide

This guide provides the minimal steps to get our full software stack running locally for development and testing purposes. You will have a complete working environment up and running in minutes.

Important

This setup is designed exclusively for local development and testing. It is not production-ready and should never be exposed to external networks or the internet.

Prerequisites​

  • Docker installed on your local machine
  • Deployment credentials and files (provided by your implementation team):
    • Container registry login command with credentials (docker login -u ...)
    • Docker Compose configuration file
    • Environment and configuration files

Log in to Docker​

Use the provided credentials to log in to Docker.

docker login -u [username] -p [password] [registry-url].azurecr.io

Pull the images​

docker compose pull     # could be `docker-compose pull` depending on your docker version

Configure local domain resolution​

Your deployment uses service names, like keycloak, that need to resolve to your local machine. The /hosts file tells your computer how to resolve domain names locally, before it asks DNS servers.

  1. Open your hosts file:

sudo vim /etc/hosts     # You may need to input your system password to open the file

  1. Add the following line:

127.0.0.1 keycloak

  1. Save and exit the editor.

Now your computer will redirect keycloak to localhost instead of looking for it on the internet.

Need help editing in vim?

  1. Press o to create a new line and enter insert mode

  2. Type: 127.0.0.1 keycloak

  3. Press Esc to exit insert mode

  4. Type :wq and press Enter to save and quit

Quick reference:

  • o = new line + insert mode
  • Esc = exit insert mode
  • :wq = save and quit
  • :q! = quit without saving

Deploy ingress and authentication server​

Your deployment uses Traefik to route incoming traffic and Keycloak to authenticate users.

  1. Start Traefik and Keycloak:

docker compose up traefik keycloak -d

Configure authentication server and OAuth2 proxy​

Before starting the full application stack, you need to configure Keycloak to recognize and authenticate your application. This involves creating an OAuth2 "client" (which represents your application) and configuring how users will be redirected for login/logout.

  1. Open http://keycloak:8080 and log in using the admin credentials admin and admin (defined in ./env/.keycloak.env).

  2. Create a new client with the following settings:

  • Client ID: one-bff-client

  • Name: one-bff-client

  • Client authentication: On

  • Authorization: On

  • Authentication flow: Standard flow and Direct access grants

  • Valid redirect URIs: http://localhost/oath2/callback/*

  • Valid post logout redirect URis: http://localhost

  • Web origins: +

  1. Extract the client secret and update the OAuth2 proxy configuration:

  • In the one-bff-client, go to the "Credentials" tab and copy the Client Secret.

  • Update the OAuth2 proxy configuration at ./conf/oauth2_proxy/alpha-config.yml with the Client Secret from Keycloak:

providers:
  - provider: oidc
    clientSecret: {{CLIENT-SECRET-HERE}}

This client secret enables your OAuth2 proxy to securely communicate with Keycloak and validate user authentication tokens.

Deploy the remaining stack​

  1. docker compose up -d

Configure IAM roles​

  1. Go to Keycloak and create two new realm roles with the following names:

  • SAMPLE_ORG_EDITOR
  • SAMPLE_ORG_READER

Configure client and authentication​

  1. In Keycloak create a new client scope with the name one-bff-client.

  2. For this new client scope, configure a new mapper with the following settings:

  • Mapper type: Audience

  • Name: one-bff-audience

  • Included Client Audience: one-bff-client

  • Included Custom Audience: one-bff-client

  1. Add the new client scope to the client:

  • Go to "Clients" and choose one-bff-client

  • Add a client scope, selecting one-bff-client and adding it as the default client scope.

Create the first user​

  1. In Keycloak add a new user with the following settings:

  • Email verified: On

  • Choose a username and email for testing

  1. Map the user to the IAM roles:

  • Go to "Role mapping" and assign a role

  • Filter the selectable roles by realm roles

  • Select SAMPLE_ORG_EDITOR and SAMPLE_ORG_READER

  1. Go to "Credentials" and set a password for the user.

Sign in​

  1. Open http://localhost and sign in with your credentials.