Run from Container guide V1 (#9646)
Closes #9465 Co-authored-by: Stian Thorgersen <stian@redhat.com> Co-authored-by: Stian Thorgersen <stian@redhat.com>
This commit is contained in:
Dominik Guhr
GitHub
parent
cceeb9a5d7
commit
f70a22f583
3 changed files with 109 additions and 2 deletions
107
docs/guides/src/main/server/containers.adoc
Normal file
107
docs/guides/src/main/server/containers.adoc
Normal file
|
|
@ -0,0 +1,107 @@
|
|||
<#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 in a container"
|
||||
summary="Learn how to run Keycloak from a container image"
|
||||
priority=20
|
||||
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.
|
||||
|
||||
== 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:
|
||||
|
||||
=== 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.
|
||||
|
||||
.Dockerfile:
|
||||
[source, dockerfile]
|
||||
----
|
||||
FROM quay.io/keycloak/keycloak-x: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-x: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"]
|
||||
----
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
=== Building the docker image
|
||||
To build the actual docker image, run the following command form the Directory containing your Dockerfile:
|
||||
[source,bash]
|
||||
----
|
||||
podman|docker build . -t prebuilt_keycloak
|
||||
----
|
||||
|
||||
=== Start 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:
|
||||
[source, bash]
|
||||
----
|
||||
INFO [org.key.com.Profile] (main) Preview feature enabled: token_exchange
|
||||
----
|
||||
This 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.
|
||||
|
||||
== 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:
|
||||
|
||||
[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-x:latest \
|
||||
start-dev
|
||||
----
|
||||
|
||||
Invoking this command will spin up 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_.
|
||||
|
||||
== 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:
|
||||
|
||||
[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-x: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 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.
|
||||
|
||||
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.
|
||||
|
||||
</@tmpl.guide>
|
||||
|
|
@ -34,7 +34,7 @@ By default, Keycloak does not enable deprecated TLS protocols. In situations whe
|
|||
|
||||
<@kc.start parameters="--https-protocols=<protocol>[,<protocol>]"/>
|
||||
|
||||
To also allow TLSv1.2, use for example `kc.sh start --http-protocols=TLSv1.3,TLSv1.2`.
|
||||
To also allow TLSv1.2, use for example `kc.sh start --https-protocols=TLSv1.3,TLSv1.2`.
|
||||
|
||||
== Switch the HTTPS port
|
||||
Keycloak listens for HTTPS traffic on port `8443` by default. To change this port, use:
|
||||
|
|
@ -52,6 +52,6 @@ You can set a secure password for your truststore using the `https.trust-store.p
|
|||
If no password is set, the default password `password` is used.
|
||||
|
||||
== Securing credentials
|
||||
We recommend to not set any password in plaintext via the CLI or in `conf/keycloak.properties`, but instead using good practices such as using a vault / mounted secret. Please refer to the Vault Guide / Production deployment guide for more advice.
|
||||
We recommend to not set any password in plaintext via the CLI or in `conf/keycloak.conf`, but instead using good practices such as using a vault / mounted secret. Please refer to the Vault Guide / Production deployment guide for more advice.
|
||||
|
||||
</@tmpl.guide>
|
||||
Loading…
Reference in a new issue