Skip to main content

Quick deployment 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.
  • Access to the project's Docker Compose configuration file and associated container images.

Familiarize yourself with configuration locations​

Environment variables are located in the ./env/ directory and configuration files are located in the ./conf/ directory. The defaults will work for local development, but you can review these files to understand available customization options.

Configure local domain resolution​

  1. Open your hosts file:

sudo vim /etc/hosts

  1. Add the following line:

127.0.0.1 keycloak

  1. Save and exit the editor.

Deploy ingress and authentication server​

  1. Start Traefik (ingress controller) and Keycloak (authentication):

docker compose up traefik keycloak -d

Configure authentication server and OAuth2 proxy​

  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 } }

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.