Olvid Keycloak Configuration Guide - Running Keycloak in a Container

Running Keycloak in a Container

This guide gives the steps to run Keycloak with the Olvid Plugin in a container. This guide uses docker-compose to run the container, but you may of course use other container orchestration platforms like Kubernetes.

You should also make sure that the container will be able to connect to the Olvid server. Only the https://server.olvid.io/keycloakQuery URL needs to be accessible, but you should take this into consideration when configuring your container’s network.

1. Download the Keycloak + Olvid bundle

The Olvid Plugin is bundled with a complete Keycloak (Quarkus version) distribution. The bundle can be downloaded from:

https://static.olvid.io/keycloak/keycloak_olvid_23.0.6_3.1.0.tar.gz

You may check that the SHA-256 hash of the bundle is 15b5ed5567cdc97899e650893e4ebaeb30ebd3548bc79b161d70cb05c88ab798.

2. Build the container

In order to run Olvid in a container, you must first build the container image. Here we assume that a reverse proxy will be used to handle SSL/TLS and the container can listen in plain HTTP, on the default Keycloak HTTP port: 8080.

The Dockerfile below is based on the official Keycloak docker. In the same folder as the bundle tar you downloaded (please make sure you have only one bundle in this folder, if upgrading, remember to delete the old bundle), create a Dockerfile containing:

FROM registry.access.redhat.com/ubi8-minimal AS build-env

ENV KEYCLOAK_VERSION keycloak_olvid
ARG KEYCLOAK_DIST=keycloak*.tar.gz

RUN microdnf install -y tar gzip
RUN cd /tmp/
RUN mkdir keycloak

ADD $KEYCLOAK_DIST /tmp/keycloak/

RUN mv /tmp/keycloak/keycloak_olvid* /opt/keycloak && mkdir -p /opt/keycloak/data
RUN chmod -R g+rwX /opt/keycloak


FROM registry.access.redhat.com/ubi8-minimal
ENV LANG en_US.UTF-8

COPY --from=build-env --chown=1000:0 /opt/keycloak /opt/keycloak
RUN chmod 777 /opt/keycloak/bin/kc.sh

RUN microdnf update -y && \
    microdnf install -y --nodocs java-17-openjdk-headless glibc-langpack-en && microdnf clean all && rm -rf /var/cache/yum/* && \
    echo "keycloak:x:0:root" >> /etc/group && \
    echo "keycloak:x:1000:0:keycloak user:/opt/keycloak:/sbin/nologin" >> /etc/passwd

USER 1000

EXPOSE 8080

ENTRYPOINT [ "/opt/keycloak/bin/kc.sh" ]

Now run:

> docker build --tag keycloak-olvid .

This builds a container named keycloak-olvid that can be used in docker-compose.

3. Run the container

You may want to have a look at the official documentation to see all the options when running Keycloak in a container:

https://www.keycloak.org/server/containers

Here is a sample docker-compose.yaml file that can be adapted to your needs. This one uses PostgreSQL, but you may also use other databases supported by the container. The elements in red need to be modified.

KC_DB_URL is the database URL and database name (here we assume the database will be named keycloak).
If using another database than PostgresSQL, or using a non-standard PostgreSQL port, remember to change the KC_DB_PORT.
KC_DB_PASSWORD is the password of the keycloak user in your database. This user must have full access to the keycloak database.
KEYCLOAK_ADMIN_PASSWORD is the password of the Keycloak administration console admin that you will need to configure Keycloak.

version: '3'

services:
  keycloak:
    image: keycloak-olvid
    environment:
      KC_DB_URL: jdbc:postgresql://postgres/keycloak
      KC_DB_PORT: 5432
      KC_DB_DATABASE: keycloak
      KC_DB_USER: keycloak
      KC_DB_PASSWORD: password
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: password
      KC_HTTP_ENABLED: "true"
      KC_HTTPS_ENABLED: "false"
      KC_PROXY: edge
      KC_HOSTNAME_STRICT: "false"
      KC_HOSTNAME_STRICT_HTTPS: "false"
      KC_HTTP_RELATIVE_PATH: /auth
    ports:
      - 8080:8080
    entrypoint: ["/bin/sh", "-c", "/opt/keycloak/bin/kc.sh build --db postgres && /opt/keycloak/bin/kc.sh start --optimized"]

In this example, Keycloak runs in plain HTTP in “edge” proxy mode, meaning that it should be placed behind a reverse proxy taking care of the TLS encryption. It can still be accessed in plain HTTP on the internal IP address it is running at.

You may start your Keycloak instance by running:

> docker-compose up -d --build

Once the container is running, you may access its logs (to check for error messages) with the command:

> docker-compose logs -f keycloak

4. Configure the reverse proxy

The reverse proxy must send some required headers for Keycloak to properly work:

X-Forwarded-For
X-Forwarded-Proto
X-Forwarded-Host

Please refer to https://www.keycloak.org/server/reverseproxy for more information.

Here is a sample nginx.conf file. Again, the parts in red should be adapted.

server {
  server_name keycloak.public.dns;

  # To only redirect a specific set of paths, you may replace the line below with something of the form
  # location ~ ^(/auth/resources/|/auth/js/|/auth/realms/olvid/) {
  location /auth {
	proxy_set_header X-Forwarded-For $remote_addr;
	proxy_set_header X-Forwarded-Proto $scheme;
	proxy_set_header X-Forwarded-Host $host;

	proxy_buffer_size       128k;
	proxy_buffers           4 256k;
	proxy_busy_buffers_size 256k;

	proxy_pass http://keycloak.internal.ip:8080;
  }

  location /olvid {
	return 302 /auth/olvid/#;
  }

  location = / {
	return 302 /auth;
  }

  client_max_body_size 10M;

  listen [::]:443 ssl ipv6only=on;
  listen 443 ssl;

  ssl_certificate /etc/letsencrypt/live/keycloak.public.dns/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/keycloak.public.dns/privkey.pem;
  include /etc/letsencrypt/options-ssl-nginx.conf;
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}

Once nginx is restarted, simply open your Keycloak’s public DNS in a browser, you should see the “Welcome to Keycloak” front page.

Remember the KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD credentials you set in your docker-compose.yaml file: you will need them to sign in to the Keycloak administration console.

You can now continue with the Configuration of Keycloak