keycloak-scim/docs/guides/src/main/server/containers.adoc

<#import "/templates/guide.adoc" as tmpl>
<#import "/templates/kc.adoc" as kc>
<#import "/templates/options.adoc" as opts>
<#import "/templates/links.adoc" as links>

<@tmpl.guide
title="Running Keycloak in a container"
summary="Learn how to run Keycloak from a container image"
includedOptions="db db-url db-username db-password features hostname https-key-store-file https-key-store-password metrics-enabled">

Keycloak handles containerized environments such as Kubernetes or OpenShift as first-class citizens. This guide describes how to optimize and run the Keycloak container image to provide the best experience running a Keycloak container.

== Creating an optimized container image
For the best start up of your Keycloak container, build an optimized container image by running the `build` step before starting.

=== Building your optimized Keycloak docker image
The following `Dockerfile` creates a pre-configured Keycloak image that enables the metrics endpoint, enables the token exchange feature, and uses a PostgreSQL database.

.Dockerfile:
[source, dockerfile]
----
FROM quay.io/keycloak/keycloak:latest as builder

ENV KC_METRICS_ENABLED=true
ENV KC_FEATURES=token-exchange
ENV KC_DB=postgres
RUN /opt/keycloak/bin/kc.sh build

FROM quay.io/keycloak/keycloak:latest
COPY --from=builder /opt/keycloak/lib/quarkus/ /opt/keycloak/lib/quarkus/
WORKDIR /opt/keycloak
# for demonstration purposes only, please make sure to use proper certificates in production instead
RUN keytool -genkeypair -storepass password -storetype PKCS12 -keyalg RSA -keysize 2048 -dname "CN=server" -alias server -ext "SAN:c=DNS:localhost,IP:127.0.0.1" -keystore conf/server.keystore
ENV KEYCLOAK_ADMIN=admin
ENV KEYCLOAK_ADMIN_PASSWORD=change_me
# change these values to point to a running postgres instance
ENV KC_DB_URL=<DBURL>
ENV KC_DB_USERNAME=<DBUSERNAME>
ENV KC_DB_PASSWORD=<DBPASSWORD>
ENV KC_HOSTNAME=localhost:8443
ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start"]
----
The build process includes multiple stages:

* The `build` command applies options that create an optimized image.
* The files generated by the `build` process are copied into a new image.
* In this runner image, the specific run configuration is applied. That configuration contains a keystore, the environment-specific hostname configuration, and database configuration.
* In the entrypoint, the `start` command starts the image in production mode.

This example uses a multi-staged build to demonstrate the build and run steps.  However, you can also run this process as a single-staged docker build.

=== Building the docker image
To build the actual docker image, run the following command from the directory containing your Dockerfile:

[source,bash]
----
podman|docker build . -t prebuilt_keycloak
----

=== Starting the optimized Keycloak docker image
To start the image, run:
[source, bash]
----
podman|docker run --name optimized_keycloak -p 8443:8443 prebuilt_keycloak
----
Keycloak starts in production mode, using only secured HTTPS communication, and is available on `https://localhost:8443`.
Notice that the startup log contains the following line:
[source, bash]
----
INFO  [org.key.com.Profile] (main) Preview feature enabled: token_exchange
----
This message shows the desired feature is enabled.

Opening up `https://localhost:8443/metrics` leads to a page containing operational metrics that could be used by your monitoring solution.

== Trying Keycloak in development mode
The easiest way to try Keycloak from a container for development or testing purposes is to use the Development mode.
You use the `start-dev` command:

[source,bash]
----
podman|docker run --name keycloak_test -p 8080:8080 \
        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
        quay.io/keycloak/keycloak:latest \
        start-dev
----

Invoking this command starts the Keycloak server in development mode.

This mode should be strictly avoided in production environments because it has insecure defaults.
For more information about running Keycloak in production, take a look at the <@links.server id="configuration-production"/> guide.

== Use auto-build to run a standard keycloak container
In keeping with concepts such as immutable infrastructure, containers need to be re-provisioned routinely.
In these environments, you need containers that start fast, therefore you need to create an optimized image as described in the preceding section.
However, if your environment has different requirements, you can run a standard Keycloak image using the `--auto-build` flag.
For example:

[source, bash]
----
podman|docker run --name keycloak_auto_build -p 8080:8080 \
        -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \
        quay.io/keycloak/keycloak:latest \
        start \
        --auto-build \
        --db=postgres --features=token-exchange \
        --db-url=<JDBC-URL> --db-username=<DB-USER> --db-password=<DB-PASSWORD> \
        --https-key-store-file=<file> --https-key-store-password=<password>
----

Running this command starts a Keycloak server that detects and applies the build options first.
In the example, the line  `--db=postgres --features=token-exchange` sets the database vendor to PostgreSQL and enables the token exchange feature.

Keycloak then starts up and applies the configuration for the specific environment.
This approach significantly increases startup time and creates an image that is mutable, which is not the best practice.

</@tmpl.guide>