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 distribution. The bundle can be downloaded from:

https://static.olvid.io/keycloak/keycloak_olvid_26.3.3_4.3.2.tar.gz

You should check that the SHA-256 hash of the bundle is 732bf81ea5eaf48c2b7fd6e79103b4aaefaa65dad916c6da21752da3d39d6eb0.

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. To build the container you will need to have, in the same folder as the Dockerfile:

the bundle tar you downloaded (please make sure you have only one bundle in this folder, if upgrading, remember to delete the old bundle)
the ubi-null.sh script used during the build to minimize the Docker image size. You can download it with the command:

> wget https://olvid.io/assets/keycloak/ubi-null.sh

You can then create a Dockerfile containing:

FROM registry.access.redhat.com/ubi9 AS ubi-micro-build

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

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

ADD ubi-null.sh /tmp/
RUN bash /tmp/ubi-null.sh java-21-openjdk-headless glibc-langpack-en findutils

FROM registry.access.redhat.com/ubi9-micro
ENV LANG en_US.UTF-8

ENV KC_RUN_IN_CONTAINER true

COPY --from=ubi-micro-build /tmp/null/rootfs/ /
COPY --from=ubi-micro-build --chown=1000:0 /opt/keycloak /opt/keycloak

RUN 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.
KC_BOOTSTRAP_ADMIN_PASSWORD is the password of the Keycloak administration console admin that you will need to configure Keycloak.

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
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: password
      KC_HTTP_ENABLED: "true"
      KC_HTTPS_ENABLED: "false"
      KC_PROXY_HEADERS: xforwarded
      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 “xforwarded” proxy mode, meaning that it should be placed behind a reverse proxy taking care of the TLS encryption and adding relevant X-Forwarded-... headers. 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

Now that the container is running, you can configure the reverse proxy similarly to the non-container install.

Remember the KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_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