Merge pull request #69 from projectsyn/doc/theme

Add how-to on custom themes

docs/modules/ROOT/pages/how-tos/custom-theme.adoc

@@ -0,0 +1,67 @@
+= Configure custom theme
+
+Keycloak provides theme support for web pages and emails.
+This allows customizing the look and feel of end-user facing pages so they can be integrated with your applications.
+
+The intended approach to configure a custom theme is to bundle the theme in a container image and copy it to the correct location as an init container.
+
+== Creating custom theme
+
+A theme can provide one or more types to customize different aspects of Keycloak.
+A theme consists of: HTML templates, images, message bundles, stylesheets, scripts and theme properties.
+
+
+Follow xref:how-tos/keycloak-tls.adoc[the official guide] on how to create a custom theme
+
+Once you have created your custom theme, you'll need to package it into a container image.
+
+[source,dockerfile]
+----
+FROM docker.io/library/busybox
+
+COPY theme /theme
+
+RUN \
+  chmod -R +r /theme
+
+USER 1001:0
+----
+
+
+
+== Deploying custom theme
+
+With the theme accessible in a container image we can deploy it using an init container.
+In combination with an emptyDir volume that's shared with the Keycloak container, we copy the theme over to the right place where Keycloak will pick it up automatically.
+
+[source,yaml]
+----
+parameters:
+  keycloak:
+    extraInitContainers:
+      theme-provider:
+        image: company/keycloak-theme:v1.0.0
+        imagePullPolicy: IfNotPresent
+        command:
+          - sh
+        args:
+          - -c
+          - |
+            echo "Copying theme..."
+            cp -R /theme/* /company-theme
+        volumeMounts:
+          - name: theme
+            mountPath: /company-theme
+    extraVolumes:
+      theme:
+        emptyDir: {}
+    extraVolumeMounts:
+      theme:
+        readOnly: true
+        mountPath: /opt/jboss/keycloak/themes/company
+----
+
+[TIP]
+====
+See xref:how-tos/keycloak-tls.adoc[the official deploy guide] for a more detailed look into deploying themes.
+====

docs/modules/ROOT/partials/nav.adoc

@@ -10,6 +10,7 @@
 * xref:how-tos/db-tls.adoc[Encrypt database connection]
 * xref:how-tos/keycloak-tls.adoc[Setup a TLS certificate for Keycloak]
 * xref:how-tos/configure-ingress.adoc[Configure Keycloak ingress]
+* xref:how-tos/custom-theme.adoc[Configure custom theme]
 * xref:how-tos/change-passwords.adoc[Change passwords]
 * xref:how-tos/upgrade-1.x-to-2.x.adoc[Upgrade 1.x to 2.x]
 * xref:how-tos/upgrade-2.x-to-3.x.adoc[Upgrade 2.x to 3.x]