Align docs with AsciiDoc best practices for downstream processing (#16996)
CIAM-5054
This commit is contained in:
Alexander Schwartz
GitHub
parent
686417ec29
commit
e03105e685
21 changed files with 31 additions and 33 deletions
4
docs/guides/src/main/.asciidoctorconfig
Normal file
4
docs/guides/src/main/.asciidoctorconfig
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
// Configure settings for the preview in IntelliJ
|
||||
// see: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoctorconfig-file.html
|
||||
:imagesdir: {asciidoctorconfigdir}/images
|
||||
:icons: font
|
||||
|
|
@ -10,7 +10,7 @@ summary="Get started with Keycloak on Docker">
|
|||
:links-admin-console: http://localhost:8080/admin[Keycloak Admin Console]
|
||||
:links-account-console: http://localhost:8080/realms/myrealm/account[Keycloak Account Console]
|
||||
|
||||
## Before you start
|
||||
== Before you start
|
||||
|
||||
Make sure you have Docker installed.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ summary="Get started with Keycloak on Kubernetes">
|
|||
:links-admin-console: Keycloak Admin Console
|
||||
:links-account-console: Keycloak Account Console
|
||||
|
||||
## Before you start
|
||||
== Before you start
|
||||
|
||||
Make sure you have Minikube installed, ideally with the Ingress addon enabled.
|
||||
|
||||
|
|
@ -25,7 +25,7 @@ If the Ingress addon is not enabled run the following to enable it:
|
|||
minikube addons enable ingress
|
||||
----
|
||||
|
||||
## Run Keycloak
|
||||
== Run Keycloak
|
||||
|
||||
The Keycloak QuickStarts repository includes some example files to help deploy Keycloak to Kubernetes.
|
||||
|
||||
|
|
@ -39,7 +39,7 @@ kubectl create -f https://raw.githubusercontent.com/keycloak/keycloak-quickstart
|
|||
This will start Keycloak on Kubernetes. It will also create an initial admin user with username `admin` and password
|
||||
`admin`.
|
||||
|
||||
### Access Keycloak with Ingress addon enabled
|
||||
=== Access Keycloak with Ingress addon enabled
|
||||
|
||||
Start by creating an Ingress for Keycloak:
|
||||
|
||||
|
|
@ -68,7 +68,7 @@ echo ""
|
|||
Remember these URLs as you will need them throughout this guide. The URL for the account console won't work
|
||||
right now as you will need to create the realm first.
|
||||
|
||||
### Access Keycloak without Ingress
|
||||
=== Access Keycloak without Ingress
|
||||
|
||||
If you don't have the Ingress addon enabled, first run in a separate shell:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
<#import "/templates/guide.adoc" as tmpl>
|
||||
|
||||
<@tmpl.guide
|
||||
title="Openshift"
|
||||
summary="Get started with Keycloak on Openshift">
|
||||
title="OpenShift"
|
||||
summary="Get started with Keycloak on OpenShift">
|
||||
|
||||
:links-admin-console: Keycloak Admin Console
|
||||
:links-account-console: Keycloak Account Console
|
||||
|
||||
## Before you start
|
||||
== Before you start
|
||||
|
||||
Install https://code-ready.github.io/crc/[Red Hat Code Ready Containers] and follow the steps in the documentation to install a
|
||||
local OpenShift cluster.
|
||||
|
|
@ -21,7 +21,7 @@ crc status
|
|||
|
||||
If everything is OK you should see an output similar to this:
|
||||
|
||||
[source,bash,subs="attributes+"]
|
||||
[source,subs="attributes+"]
|
||||
----
|
||||
CRC VM: Running
|
||||
OpenShift: Running
|
||||
|
|
@ -42,7 +42,7 @@ For this guide, we are going to create a new project called `keycloak`. For that
|
|||
oc new-project keycloak
|
||||
----
|
||||
|
||||
## Run Keycloak
|
||||
== Run Keycloak
|
||||
|
||||
To spin up a Keycloak server in your project, execute the following command:
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ summary="Get started with Keycloak on Podman">
|
|||
:links-admin-console: http://localhost:8080/admin[Keycloak Admin Console]
|
||||
:links-account-console: http://localhost:8080/realms/myrealm/account[Keycloak Account Console]
|
||||
|
||||
## Before you start
|
||||
== Before you start
|
||||
|
||||
Make sure you have Podman installed.
|
||||
|
||||
|
|
|
|||
|
|
@ -8,11 +8,11 @@ summary="Get started with Keycloak on bare metal">
|
|||
:links-admin-console: http://localhost:8080/admin[Keycloak Admin Console]
|
||||
:links-account-console: http://localhost:8080/realms/myrealm/account[Keycloak Account Console]
|
||||
|
||||
## Before you start
|
||||
== Before you start
|
||||
|
||||
Make sure you have https://openjdk.java.net/[OpenJDK 11] or newer installed.
|
||||
|
||||
## Download Keycloak
|
||||
== Download Keycloak
|
||||
|
||||
First step is to download and extract https://github.com/keycloak/keycloak/releases/download/{version}/keycloak-{version}.zip[keycloak-{version}.zip]
|
||||
from the Keycloak website.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
## Create an admin user
|
||||
== Create an admin user
|
||||
|
||||
Keycloak does not come with a default admin user, which means before you can start using Keycloak you need to create
|
||||
an admin user.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
## Secure your first app
|
||||
== Secure your first app
|
||||
|
||||
Let's try to secure our first application. First step is to register this application with your Keycloak instance:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
## Login to account console
|
||||
== Login to account console
|
||||
|
||||
Let's now try to login to the account console to verify the user is configured correctly.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
## Next
|
||||
== Next
|
||||
|
||||
Before you go and run Keycloak in production there are a few more things that you will want to do, including:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
## Login to the admin console
|
||||
== Login to the admin console
|
||||
|
||||
Go to the {links-admin-console} and login with the username and password
|
||||
you created earlier.
|
||||
|
||||
## Create a realm
|
||||
== Create a realm
|
||||
|
||||
A realm in Keycloak is the equivalent of a tenant. It allows creating isolated groups of applications and users. By default
|
||||
there is a single realm in Keycloak called `master`. This is dedicated to manage Keycloak and should not be used for
|
||||
|
|
@ -19,7 +19,7 @@ Let's create our first realm.
|
|||
|
||||
image::add-realm.png[Add Realm]
|
||||
|
||||
## Create a user
|
||||
== Create a user
|
||||
|
||||
Initially there are no users in a new realm, so let's create one:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
## Start Keycloak
|
||||
== Start Keycloak
|
||||
|
||||
From a terminal start Keycloak with the following command:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
## Start Keycloak
|
||||
== Start Keycloak
|
||||
|
||||
From a terminal open the directory keycloak-{version}, then to start Keycloak run the following command.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
## Test your setup
|
||||
== Test your setup
|
||||
|
||||
To make it easy for you we have a SPA testing application available on the https://www.keycloak.org/app/[Keycloak website].
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,6 @@ summary="How to customize and optimize the Keycloak Container">
|
|||
|
||||
The Keycloak Custom Resource (CR) give you the possibility to specify a custom container image for the Keycloak server.
|
||||
|
||||
.Note:
|
||||
[NOTE]
|
||||
To ensure full compatibility of Operator and Operand,
|
||||
make sure that the version of Keycloak release used in the custom image is aligned with the version of the operator.
|
||||
|
|
@ -44,7 +43,6 @@ spec:
|
|||
hostname: test.keycloak.org
|
||||
----
|
||||
|
||||
.Note:
|
||||
[NOTE]
|
||||
Using custom images, every build time option passed either through a dedicated field or the `additionalOptions` key will be ignored.
|
||||
|
||||
|
|
|
|||
|
|
@ -12,11 +12,9 @@ summary="How to perform an automated Keycloak Realm Import using the operator">
|
|||
|
||||
The Keycloak Operator ships with the ability to automatically perform a realm import for the Keycloak Deployment.
|
||||
|
||||
.Note:
|
||||
[NOTE]
|
||||
If a Realm with the same name already exists in Keycloak it will not be overwritten.
|
||||
|
||||
.Note:
|
||||
[NOTE]
|
||||
The Realm Import CR only supports creation of new realms and doesn't update or delete those. +
|
||||
Changes to the realm performed directly on Keycloak are not synced back in the CR.
|
||||
|
|
|
|||
|
|
@ -72,7 +72,7 @@ db-url-host=mykeycloakdb
|
|||
----
|
||||
|
||||
=== Using environment variables for configuration values
|
||||
It is possible to use placeholders to resolve an environment specific value from environment variables inside the keycloak.conf file by using the `${r"${ENV_VAR}"}` syntax:
|
||||
It is possible to use placeholders to resolve an environment specific value from environment variables inside the keycloak.conf file by using the `${r"++${ENV_VAR}++"}` syntax:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
|
|
|||
|
|
@ -40,8 +40,7 @@ This command includes the minimum settings needed to connect to the database.
|
|||
|
||||
The default schema is `keycloak`, but you can change it by using the `db-schema` configuration option.
|
||||
|
||||
.Warning:
|
||||
[NOTE]
|
||||
[WARNING]
|
||||
Do NOT use the `--optimized` flag for the `start` command if you want to use a particular DB (except the H2).
|
||||
Executing the build phase before starting the server instance is necessary.
|
||||
You can achieve it either by starting the instance without the `--optimized` flag,
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ can be categorized into three main groups:
|
|||
|
||||
The base URL for each group has an important impact on how tokens are issued and validated, on how links are created for actions that require the user
|
||||
to be redirected to Keycloak (for example, when resetting password through email links), and, most importantly, how applications will
|
||||
discover these endpoints when fetching the OpenID Connect Discovery Document from `realms/{realm-name}/.well-known/openid-configuration`.
|
||||
discover these endpoints when fetching the OpenID Connect Discovery Document from `realms/++{realm-name}++/.well-known/openid-configuration`.
|
||||
|
||||
=== Frontend
|
||||
|
||||
|
|
|
|||
|
|
@ -85,7 +85,7 @@ The format string supports the symbols in the following table:
|
|||
|Symbol|Summary|Description
|
||||
|%%|%|Renders a simple % character.
|
||||
|%c|Category|Renders the log category name.
|
||||
|%d{xxx}|Date|Renders a date with the given date format string.String syntax defined by `java.text.SimpleDateFormat`
|
||||
|++%d{xxx}++|Date|Renders a date with the given date format string.String syntax defined by `java.text.SimpleDateFormat`
|
||||
|%e|Exception|Renders a thrown exception.
|
||||
|%h|Hostname|Renders the simple host name.
|
||||
|%H|Qualified host name|Renders the fully qualified hostname, which may be the same as the simple host name, depending on the OS configuration.
|
||||
|
|
|
|||
|
|
@ -155,7 +155,6 @@ The following table shows the recommended paths to expose.
|
|||
|
||||
|===
|
||||
|
||||
.Note:
|
||||
[NOTE]
|
||||
As it's true that the `js` path is needed for internal clients like the account console, it's good practice to use `keycloak.js` from a JavaScript package manager like npm or yarn for your external clients.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue