From 2b2287d1ee3bf3b4db12beb02599819ed1ba0ef5 Mon Sep 17 00:00:00 2001 From: Pedro Igor Date: Fri, 5 Aug 2022 08:52:10 -0300 Subject: [PATCH] More information to the container guide Closes #13569 --- docs/guides/src/main/server/containers.adoc | 59 +++++++++++++-------- 1 file changed, 37 insertions(+), 22 deletions(-) diff --git a/docs/guides/src/main/server/containers.adoc b/docs/guides/src/main/server/containers.adoc index 8b01bc8ac1..48f8eed2b9 100644 --- a/docs/guides/src/main/server/containers.adoc +++ b/docs/guides/src/main/server/containers.adoc @@ -24,19 +24,21 @@ The following `Dockerfile` creates a pre-configured Keycloak image that enables ---- FROM quay.io/keycloak/keycloak:latest as builder +# Enable health and metrics support ENV KC_HEALTH_ENABLED=true ENV KC_METRICS_ENABLED=true -ENV KC_FEATURES=token-exchange + +# Configure a database vendor ENV KC_DB=postgres -# Install custom providers -RUN curl -sL https://github.com/aerogear/keycloak-metrics-spi/releases/download/2.5.3/keycloak-metrics-spi-2.5.3.jar -o /opt/keycloak/providers/keycloak-metrics-spi-2.5.3.jar + +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 RUN /opt/keycloak/bin/kc.sh build FROM quay.io/keycloak/keycloak:latest COPY --from=builder /opt/keycloak/ /opt/keycloak/ -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 + # change these values to point to a running postgres instance ENV KC_DB_URL= ENV KC_DB_USERNAME= @@ -46,17 +48,17 @@ ENTRYPOINT ["/opt/keycloak/bin/kc.sh"] ---- The build process includes multiple stages: -* The `build` command applies options and includes custom providers to create an optimized image. +* Run the `build` command to set server build options to create an optimized image. * The files generated by the `build` stage 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 final image, additional configuration options for the hostname and database are set so that you don't need to set them again when running the container. * In the entrypoint, the `kc.sh` enables access to all the distribution sub-commands. -This example uses a multi-staged build to demonstrate the build and run steps. However, you can also build a single-staged docker image by removing the following two lines: +To install custom providers, you just need to define a step to include the JAR file(s) into the `/opt/keycloak/providers` directory: [source, dockerfile] ---- -FROM quay.io/keycloak/keycloak:latest -COPY --from=builder /opt/keycloak/ /opt/keycloak/ +# A example build step that downloads a JAR file from a URL and adds it to the providers directory +RUN curl -sL -o /opt/keycloak/providers/myprovider.jar ---- === Building the docker image @@ -64,37 +66,50 @@ To build the actual docker image, run the following command from the directory c [source,bash] ---- -podman|docker build . -t prebuilt_keycloak +podman|docker build . -t mykeycloak ---- === Starting the optimized Keycloak docker image To start the image, run: + [source, bash] ---- -podman|docker run --name optimized_keycloak -p 8443:8443 \ +podman|docker run --name mykeycloak -p 8443:8443 \ -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \ - prebuilt_keycloak \ + mykeycloak \ start --optimized ---- + 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. Health check endpoints are available at `https://localhost:8443/health`, `https://localhost:8443/health/ready` and `https://localhost:8443/health/live`. Opening up `https://localhost:8443/metrics` leads to a page containing operational metrics that could be used by your monitoring solution. +== Exposing the container to a different port + +By default, the server is listening for `http` and `https` requests using the ports `8080` and `8443`, respectively. + +If you want to expose the container using a different port, you need to set the `hostname-port` accordingly: + +. Exposing the container using a port other than the default ports +[source, bash] +---- +podman|docker run --name mykeycloak -p 3000:8443 \ + -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \ + mykeycloak \ + start --optimized --hostname-port=3000 +---- + +By setting the `hostname-port` option you can now access the server at `https://localhost:3000`. + == 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 \ +podman|docker run --name mykeycloak -p 8080:8080 \ -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \ quay.io/keycloak/keycloak:latest \ start-dev @@ -113,7 +128,7 @@ For example: [source, bash] ---- -podman|docker run --name keycloak_unoptimized -p 8080:8080 \ +podman|docker run --name mykeycloak -p 8080:8080 \ -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=change_me \ quay.io/keycloak/keycloak:latest \ start \