nixos/keycloak: convert manual chapter to MD

3 files changed, 313 insertions, 195 deletions

diff --git a/nixos/modules/services/web-apps/keycloak.md b/nixos/modules/services/web-apps/keycloak.md
new file mode 100644
index 0000000000000..aa8de40d642b1
--- /dev/null
+++ b/nixos/modules/services/web-apps/keycloak.md
@@ -0,0 +1,141 @@
+# Keycloak {#module-services-keycloak}
+
+[Keycloak](https://www.keycloak.org/) is an
+open source identity and access management server with support for
+[OpenID Connect](https://openid.net/connect/),
+[OAUTH 2.0](https://oauth.net/2/) and
+[SAML 2.0](https://en.wikipedia.org/wiki/SAML_2.0).
+
+## Administration {#module-services-keycloak-admin}
+
+An administrative user with the username
+`admin` is automatically created in the
+`master` realm. Its initial password can be
+configured by setting [](#opt-services.keycloak.initialAdminPassword)
+and defaults to `changeme`. The password is
+not stored safely and should be changed immediately in the
+admin panel.
+
+Refer to the [Keycloak Server Administration Guide](
+  https://www.keycloak.org/docs/latest/server_admin/index.html
+) for information on
+how to administer your Keycloak
+instance.
+
+## Database access {#module-services-keycloak-database}
+
+Keycloak can be used with either PostgreSQL, MariaDB or
+MySQL. Which one is used can be
+configured in [](#opt-services.keycloak.database.type). The selected
+database will automatically be enabled and a database and role
+created unless [](#opt-services.keycloak.database.host) is changed
+from its default of `localhost` or
+[](#opt-services.keycloak.database.createLocally) is set to `false`.
+
+External database access can also be configured by setting
+[](#opt-services.keycloak.database.host),
+[](#opt-services.keycloak.database.name),
+[](#opt-services.keycloak.database.username),
+[](#opt-services.keycloak.database.useSSL) and
+[](#opt-services.keycloak.database.caCert) as
+appropriate. Note that you need to manually create the database
+and allow the configured database user full access to it.
+
+[](#opt-services.keycloak.database.passwordFile)
+must be set to the path to a file containing the password used
+to log in to the database. If [](#opt-services.keycloak.database.host)
+and [](#opt-services.keycloak.database.createLocally)
+are kept at their defaults, the database role
+`keycloak` with that password is provisioned
+on the local database instance.
+
+::: {.warning}
+The path should be provided as a string, not a Nix path, since Nix
+paths are copied into the world readable Nix store.
+:::
+
+## Hostname {#module-services-keycloak-hostname}
+
+The hostname is used to build the public URL used as base for
+all frontend requests and must be configured through
+[](#opt-services.keycloak.settings.hostname).
+
+::: {.note}
+If you're migrating an old Wildfly based Keycloak instance
+and want to keep compatibility with your current clients,
+you'll likely want to set [](#opt-services.keycloak.settings.http-relative-path)
+to `/auth`. See the option description
+for more details.
+:::
+
+[](#opt-services.keycloak.settings.hostname-strict-backchannel)
+determines whether Keycloak should force all requests to go
+through the frontend URL. By default,
+Keycloak allows backend requests to
+instead use its local hostname or IP address and may also
+advertise it to clients through its OpenID Connect Discovery
+endpoint.
+
+For more information on hostname configuration, see the [Hostname
+section of the Keycloak Server Installation and Configuration
+Guide](https://www.keycloak.org/server/hostname).
+
+## Setting up TLS/SSL {#module-services-keycloak-tls}
+
+By default, Keycloak won't accept
+unsecured HTTP connections originating from outside its local
+network.
+
+HTTPS support requires a TLS/SSL certificate and a private key,
+both [PEM formatted](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail).
+Their paths should be set through
+[](#opt-services.keycloak.sslCertificate) and
+[](#opt-services.keycloak.sslCertificateKey).
+
+::: {.warning}
+ The paths should be provided as a strings, not a Nix paths,
+since Nix paths are copied into the world readable Nix store.
+:::
+
+## Themes {#module-services-keycloak-themes}
+
+You can package custom themes and make them visible to
+Keycloak through [](#opt-services.keycloak.themes). See the
+[Themes section of the Keycloak Server Development Guide](
+  https://www.keycloak.org/docs/latest/server_development/#_themes
+) and the description of the aforementioned NixOS option for
+more information.
+
+## Configuration file settings {#module-services-keycloak-settings}
+
+Keycloak server configuration parameters can be set in
+[](#opt-services.keycloak.settings). These correspond
+directly to options in
+{file}`conf/keycloak.conf`. Some of the most
+important parameters are documented as suboptions, the rest can
+be found in the [All
+configuration section of the Keycloak Server Installation and
+Configuration Guide](https://www.keycloak.org/server/all-config).
+
+Options containing secret data should be set to an attribute
+set containing the attribute `_secret` - a
+string pointing to a file containing the value the option
+should be set to. See the description of
+[](#opt-services.keycloak.settings) for an example.
+
+## Example configuration {#module-services-keycloak-example-config}
+
+A basic configuration with some custom settings could look like this:
+```
+services.keycloak = {
+  enable = true;
+  settings = {
+    hostname = "keycloak.example.com";
+    hostname-strict-backchannel = true;
+  };
+  initialAdminPassword = "e6Wcm0RrtegMEHl";  # change on first login
+  sslCertificate = "/run/keys/ssl_cert";
+  sslCertificateKey = "/run/keys/ssl_key";
+  database.passwordFile = "/run/keys/db_password";
+};
+```
diff --git a/nixos/modules/services/web-apps/keycloak.nix b/nixos/modules/services/web-apps/keycloak.nix
index d52190a28648e..a1f13f159f94c 100644
--- a/nixos/modules/services/web-apps/keycloak.nix
+++ b/nixos/modules/services/web-apps/keycloak.nix
@@ -674,6 +674,8 @@ in
           mkIf createLocalMySQL (mkDefault dbPkg);
       };
 
+  # Don't edit the docbook xml directly, edit the md and generate it:
+  # `pandoc keycloak.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > keycloak.xml`
   meta.doc = ./keycloak.xml;
   meta.maintainers = [ maintainers.talyz ];
 }
diff --git a/nixos/modules/services/web-apps/keycloak.xml b/nixos/modules/services/web-apps/keycloak.xml
index 0d95ee3575a59..f6602a3c70df8 100644
--- a/nixos/modules/services/web-apps/keycloak.xml
+++ b/nixos/modules/services/web-apps/keycloak.xml
@@ -1,202 +1,177 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="module-services-keycloak">
- <title>Keycloak</title>
- <para>
-   <link xlink:href="https://www.keycloak.org/">Keycloak</link> is an
-   open source identity and access management server with support for
-   <link xlink:href="https://openid.net/connect/">OpenID
-   Connect</link>, <link xlink:href="https://oauth.net/2/">OAUTH
-   2.0</link> and <link
-   xlink:href="https://en.wikipedia.org/wiki/SAML_2.0">SAML
-   2.0</link>.
- </para>
-   <section xml:id="module-services-keycloak-admin">
-     <title>Administration</title>
-     <para>
-       An administrative user with the username
-       <literal>admin</literal> is automatically created in the
-       <literal>master</literal> realm. Its initial password can be
-       configured by setting <xref linkend="opt-services.keycloak.initialAdminPassword" />
-       and defaults to <literal>changeme</literal>. The password is
-       not stored safely and should be changed immediately in the
-       admin panel.
-     </para>
-
-     <para>
-       Refer to the <link
-       xlink:href="https://www.keycloak.org/docs/latest/server_admin/index.html">
-       Keycloak Server Administration Guide</link> for information on
-       how to administer your Keycloak
-       instance.
-     </para>
-   </section>
-
-   <section xml:id="module-services-keycloak-database">
-     <title>Database access</title>
-     <para>
-       Keycloak can be used with either
-       PostgreSQL,
-       MariaDB or
-       MySQL. Which one is used can be
-       configured in <xref
-       linkend="opt-services.keycloak.database.type" />. The selected
-       database will automatically be enabled and a database and role
-       created unless <xref
-       linkend="opt-services.keycloak.database.host" /> is changed
-       from its default of <literal>localhost</literal> or <xref
-       linkend="opt-services.keycloak.database.createLocally" /> is
-       set to <literal>false</literal>.
-     </para>
-
-     <para>
-       External database access can also be configured by setting
-       <xref linkend="opt-services.keycloak.database.host" />, <xref
-       linkend="opt-services.keycloak.database.name" />, <xref
-       linkend="opt-services.keycloak.database.username" />, <xref
-       linkend="opt-services.keycloak.database.useSSL" /> and <xref
-       linkend="opt-services.keycloak.database.caCert" /> as
-       appropriate. Note that you need to manually create the database
-       and allow the configured database user full access to it.
-     </para>
-
-     <para>
-       <xref linkend="opt-services.keycloak.database.passwordFile" />
-       must be set to the path to a file containing the password used
-       to log in to the database. If <xref linkend="opt-services.keycloak.database.host" />
-       and <xref linkend="opt-services.keycloak.database.createLocally" />
-       are kept at their defaults, the database role
-       <literal>keycloak</literal> with that password is provisioned
-       on the local database instance.
-     </para>
-
-     <warning>
-       <para>
-         The path should be provided as a string, not a Nix path, since Nix
-         paths are copied into the world readable Nix store.
-       </para>
-     </warning>
-   </section>
-
-   <section xml:id="module-services-keycloak-hostname">
-     <title>Hostname</title>
-     <para>
-       The hostname is used to build the public URL used as base for
-       all frontend requests and must be configured through <xref
-       linkend="opt-services.keycloak.settings.hostname" />.
-     </para>
-
-     <note>
-       <para>
-         If you're migrating an old Wildfly based Keycloak instance
-         and want to keep compatibility with your current clients,
-         you'll likely want to set <xref
-         linkend="opt-services.keycloak.settings.http-relative-path"
-         /> to <literal>/auth</literal>. See the option description
-         for more details.
-       </para>
-     </note>
-
-     <para>
-       <xref linkend="opt-services.keycloak.settings.hostname-strict-backchannel" />
-       determines whether Keycloak should force all requests to go
-       through the frontend URL. By default,
-       Keycloak allows backend requests to
-       instead use its local hostname or IP address and may also
-       advertise it to clients through its OpenID Connect Discovery
-       endpoint.
-     </para>
-
-     <para>
-        For more information on hostname configuration, see the <link
-        xlink:href="https://www.keycloak.org/server/hostname">Hostname
-        section of the Keycloak Server Installation and Configuration
-        Guide</link>.
-     </para>
-   </section>
-
-   <section xml:id="module-services-keycloak-tls">
-     <title>Setting up TLS/SSL</title>
-     <para>
-       By default, Keycloak won't accept
-       unsecured HTTP connections originating from outside its local
-       network.
-     </para>
-
-     <para>
-       HTTPS support requires a TLS/SSL certificate and a private key,
-       both <link
-       xlink:href="https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail">PEM
-       formatted</link>. Their paths should be set through <xref
-       linkend="opt-services.keycloak.sslCertificate" /> and <xref
-       linkend="opt-services.keycloak.sslCertificateKey" />.
-     </para>
-
-     <warning>
-       <para>
-         The paths should be provided as a strings, not a Nix paths,
-         since Nix paths are copied into the world readable Nix store.
-       </para>
-     </warning>
-   </section>
-
-   <section xml:id="module-services-keycloak-themes">
-     <title>Themes</title>
-     <para>
-        You can package custom themes and make them visible to
-        Keycloak through <xref linkend="opt-services.keycloak.themes"
-        />. See the <link
-        xlink:href="https://www.keycloak.org/docs/latest/server_development/#_themes">
-        Themes section of the Keycloak Server Development Guide</link>
-        and the description of the aforementioned NixOS option for
-        more information.
-     </para>
-   </section>
-
-   <section xml:id="module-services-keycloak-settings">
-     <title>Configuration file settings</title>
-     <para>
-       Keycloak server configuration parameters can be set in <xref
-       linkend="opt-services.keycloak.settings" />. These correspond
-       directly to options in
-       <filename>conf/keycloak.conf</filename>. Some of the most
-       important parameters are documented as suboptions, the rest can
-       be found in the <link
-       xlink:href="https://www.keycloak.org/server/all-config">All
-       configuration section of the Keycloak Server Installation and
-       Configuration Guide</link>.
-     </para>
-
-     <para>
-       Options containing secret data should be set to an attribute
-       set containing the attribute <literal>_secret</literal> - a
-       string pointing to a file containing the value the option
-       should be set to. See the description of <xref
-       linkend="opt-services.keycloak.settings" /> for an example.
-     </para>
-   </section>
-
-
-   <section xml:id="module-services-keycloak-example-config">
-     <title>Example configuration</title>
-     <para>
-       A basic configuration with some custom settings could look like this:
-<programlisting>
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-keycloak">
+  <title>Keycloak</title>
+  <para>
+    <link xlink:href="https://www.keycloak.org/">Keycloak</link> is an
+    open source identity and access management server with support for
+    <link xlink:href="https://openid.net/connect/">OpenID
+    Connect</link>, <link xlink:href="https://oauth.net/2/">OAUTH
+    2.0</link> and
+    <link xlink:href="https://en.wikipedia.org/wiki/SAML_2.0">SAML
+    2.0</link>.
+  </para>
+  <section xml:id="module-services-keycloak-admin">
+    <title>Administration</title>
+    <para>
+      An administrative user with the username <literal>admin</literal>
+      is automatically created in the <literal>master</literal> realm.
+      Its initial password can be configured by setting
+      <xref linkend="opt-services.keycloak.initialAdminPassword"></xref>
+      and defaults to <literal>changeme</literal>. The password is not
+      stored safely and should be changed immediately in the admin
+      panel.
+    </para>
+    <para>
+      Refer to the
+      <link xlink:href="https://www.keycloak.org/docs/latest/server_admin/index.html">Keycloak
+      Server Administration Guide</link> for information on how to
+      administer your Keycloak instance.
+    </para>
+  </section>
+  <section xml:id="module-services-keycloak-database">
+    <title>Database access</title>
+    <para>
+      Keycloak can be used with either PostgreSQL, MariaDB or MySQL.
+      Which one is used can be configured in
+      <xref linkend="opt-services.keycloak.database.type"></xref>. The
+      selected database will automatically be enabled and a database and
+      role created unless
+      <xref linkend="opt-services.keycloak.database.host"></xref> is
+      changed from its default of <literal>localhost</literal> or
+      <xref linkend="opt-services.keycloak.database.createLocally"></xref>
+      is set to <literal>false</literal>.
+    </para>
+    <para>
+      External database access can also be configured by setting
+      <xref linkend="opt-services.keycloak.database.host"></xref>,
+      <xref linkend="opt-services.keycloak.database.name"></xref>,
+      <xref linkend="opt-services.keycloak.database.username"></xref>,
+      <xref linkend="opt-services.keycloak.database.useSSL"></xref> and
+      <xref linkend="opt-services.keycloak.database.caCert"></xref> as
+      appropriate. Note that you need to manually create the database
+      and allow the configured database user full access to it.
+    </para>
+    <para>
+      <xref linkend="opt-services.keycloak.database.passwordFile"></xref>
+      must be set to the path to a file containing the password used to
+      log in to the database. If
+      <xref linkend="opt-services.keycloak.database.host"></xref> and
+      <xref linkend="opt-services.keycloak.database.createLocally"></xref>
+      are kept at their defaults, the database role
+      <literal>keycloak</literal> with that password is provisioned on
+      the local database instance.
+    </para>
+    <warning>
+      <para>
+        The path should be provided as a string, not a Nix path, since
+        Nix paths are copied into the world readable Nix store.
+      </para>
+    </warning>
+  </section>
+  <section xml:id="module-services-keycloak-hostname">
+    <title>Hostname</title>
+    <para>
+      The hostname is used to build the public URL used as base for all
+      frontend requests and must be configured through
+      <xref linkend="opt-services.keycloak.settings.hostname"></xref>.
+    </para>
+    <note>
+      <para>
+        If you're migrating an old Wildfly based Keycloak instance and
+        want to keep compatibility with your current clients, you'll
+        likely want to set
+        <xref linkend="opt-services.keycloak.settings.http-relative-path"></xref>
+        to <literal>/auth</literal>. See the option description for more
+        details.
+      </para>
+    </note>
+    <para>
+      <xref linkend="opt-services.keycloak.settings.hostname-strict-backchannel"></xref>
+      determines whether Keycloak should force all requests to go
+      through the frontend URL. By default, Keycloak allows backend
+      requests to instead use its local hostname or IP address and may
+      also advertise it to clients through its OpenID Connect Discovery
+      endpoint.
+    </para>
+    <para>
+      For more information on hostname configuration, see the
+      <link xlink:href="https://www.keycloak.org/server/hostname">Hostname
+      section of the Keycloak Server Installation and Configuration
+      Guide</link>.
+    </para>
+  </section>
+  <section xml:id="module-services-keycloak-tls">
+    <title>Setting up TLS/SSL</title>
+    <para>
+      By default, Keycloak won't accept unsecured HTTP connections
+      originating from outside its local network.
+    </para>
+    <para>
+      HTTPS support requires a TLS/SSL certificate and a private key,
+      both
+      <link xlink:href="https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail">PEM
+      formatted</link>. Their paths should be set through
+      <xref linkend="opt-services.keycloak.sslCertificate"></xref> and
+      <xref linkend="opt-services.keycloak.sslCertificateKey"></xref>.
+    </para>
+    <warning>
+      <para>
+        The paths should be provided as a strings, not a Nix paths,
+        since Nix paths are copied into the world readable Nix store.
+      </para>
+    </warning>
+  </section>
+  <section xml:id="module-services-keycloak-themes">
+    <title>Themes</title>
+    <para>
+      You can package custom themes and make them visible to Keycloak
+      through <xref linkend="opt-services.keycloak.themes"></xref>. See
+      the
+      <link xlink:href="https://www.keycloak.org/docs/latest/server_development/#_themes">Themes
+      section of the Keycloak Server Development Guide</link> and the
+      description of the aforementioned NixOS option for more
+      information.
+    </para>
+  </section>
+  <section xml:id="module-services-keycloak-settings">
+    <title>Configuration file settings</title>
+    <para>
+      Keycloak server configuration parameters can be set in
+      <xref linkend="opt-services.keycloak.settings"></xref>. These
+      correspond directly to options in
+      <filename>conf/keycloak.conf</filename>. Some of the most
+      important parameters are documented as suboptions, the rest can be
+      found in the
+      <link xlink:href="https://www.keycloak.org/server/all-config">All
+      configuration section of the Keycloak Server Installation and
+      Configuration Guide</link>.
+    </para>
+    <para>
+      Options containing secret data should be set to an attribute set
+      containing the attribute <literal>_secret</literal> - a string
+      pointing to a file containing the value the option should be set
+      to. See the description of
+      <xref linkend="opt-services.keycloak.settings"></xref> for an
+      example.
+    </para>
+  </section>
+  <section xml:id="module-services-keycloak-example-config">
+    <title>Example configuration</title>
+    <para>
+      A basic configuration with some custom settings could look like
+      this:
+    </para>
+    <programlisting>
 services.keycloak = {
   enable = true;
   settings = {
-    hostname = "keycloak.example.com";
+    hostname = &quot;keycloak.example.com&quot;;
     hostname-strict-backchannel = true;
   };
-  initialAdminPassword = "e6Wcm0RrtegMEHl";  # change on first login
-  sslCertificate = "/run/keys/ssl_cert";
-  sslCertificateKey = "/run/keys/ssl_key";
-  database.passwordFile = "/run/keys/db_password";
+  initialAdminPassword = &quot;e6Wcm0RrtegMEHl&quot;;  # change on first login
+  sslCertificate = &quot;/run/keys/ssl_cert&quot;;
+  sslCertificateKey = &quot;/run/keys/ssl_key&quot;;
+  database.passwordFile = &quot;/run/keys/db_password&quot;;
 };
 </programlisting>
-     </para>
-
-   </section>
- </chapter>
+  </section>
+</chapter>