libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases Packages Activity Actions

9847 Addressing comments from Dominik (#9883)

Browse source
This commit is contained in:
andymunro 2022-02-02 02:43:35 -05:00 committed by GitHub
parent 9d46b45a9c
commit 4dd27e43d1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 34 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
docs/guides/src/main/server/containers.adoc
View file

@ -4,17 +4,17 @@
<#import "/templates/links.adoc" as links>
<@tmpl.guide
title="Running in a container"
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 is handling containerized environments like Kubernetes or OpenShift as first-class-citizens. In this guide you'll learn how to run and optimize the Keycloak container image to have the best experience running a Keycloak container.
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.
== Create an optimized container image
To get the best startup experience for your Keycloak container, we recommend building an optimized container image by running the `build` step explicitly before starting:
== 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.
=== Build your optimized Keycloak docker image
The `Dockerfile` below creates a pre-configured Keycloak image which enables the metrics endpoint, the token exchange feature and uses a postgres database.
=== 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]
@ -40,35 +40,42 @@ ENV KC_DB_PASSWORD=<DBPASSWORD>
ENV KC_HOSTNAME=localhost:8443
ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start"]
----
In the first stage of this multi-staged build, we're creating the optimized image using the `build` command to apply the build options. From the `builder`, we're copying the files generated by the `build` process into a new image. In this runner image, we apply the specific run configuration, containing e.g. a keystore, the environment-specific hostname configuration and database configuration. Then this image gets started in production mode by using the `start` command in the entrypoint.
The build process includes multiple stages:
Note that this example uses a multi-staged build to explicitly showcase the build and run steps. It could also be run as a single-staged docker build.
* 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 form the Directory containing your Dockerfile:
To build the actual docker image, run the following command from the directory containing your Dockerfile:
[source,bash]
----
podman|docker build . -t prebuilt_keycloak
----
=== Start the optimized Keycloak docker image:
=== 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 up in production mode, using only secured HTTPS communication, and is available on `https://localhost:8443`.
You'll notice that the startup log contains the following line:
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 shows the desired feature is enabled.
This message shows the desired feature is enabled.
Opening up `https://localhost:8443/metrics` leads to a page containing operational metrics which could be used by your monitoring solution.
Opening up `https://localhost:8443/metrics` leads to a page containing operational metrics that could be used by your monitoring solution.
== Try Keycloak out in development mode
The easiest way to try out Keycloak from a container for development or testing purposes is using the Development mode by using the `start-dev` command:
== 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]
----
@ -78,14 +85,16 @@ podman|docker run --name keycloak_test -p 8080:8080 \
start-dev
----
Invoking this command will spin up the Keycloak server in development mode.
Invoking this command starts the Keycloak server in development mode.
Keep in mind that this mode is by no means meant to be used in production environments, as it has insecure defaults. For more information about running Keycloak in production, see _todo_link_to_running_in_production_guide_.
This mode should be strictly avoided in production environments because it has insecure defaults.
For more information about running Keycloak in production, see _todo_link_to_running_in_production_guide_.
== Use auto-build to run a standard keycloak container
Following concepts such as immutable infrastructure, containers need to be re-provisioned fairly often. In these environments, you want to have containers which start up fast by using an optimized image as described above.
However, when your environment is different, you may want to run a standard Keycloak image using the `--auto-build` flag like below:
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]
----
@ -99,8 +108,10 @@ podman|docker run --name keycloak_auto_build -p 8080:8080 \
--https-key-store-file=<file> --https-key-store-password=<password>
----
Running the above will spin up a Keycloak server which detects and applies the build configuration first. In the example, it's `--db=postgres --features=token-exchange` to set the used database vendor to postgres and enable the token exchange feature.
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 will then start up and apply the configuration for the specific environment. This approach results in a significantly bigger startup time, and an image that is mutable, and is therefor not the best practice.
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>