keycloak-scim/topics/operating-mode/domain.adoc

[[_domain-mode]]
=== Domain Clustered Mode

Running a cluster in standard mode can quickly become aggravating as the cluster grows in size.  Every time you need
to make a configuration change, you have perform it on each node in the cluster.  Domain mode solves this problem by providing
a central place to store and publish configuration.  It can be quite complex to set up, but it is worth it in the end.
This capability is built into the {{book.appserver.name}} Application Server which {{book.project.name}} derives from.

NOTE:  The guide will go over the very basics of domain mode.  Detailed steps on how to set up domain mode in a cluster should be obtained from the
       link:{{book.appserver.admindoc.link}}[{{book.appserver.admindoc.name}}].

Here are some of the basic concepts of running in domain mode.

domain controller::
  The domain controller is a process that is responsible for storing, managing, and publishing the general configuration
  for each node in the cluster.  This process is the central point from which nodes in a cluster obtain their configuration.

host controller::
  The host controller is responsible for managing server instances on a specific machine.  You configure it to run
  one or more server instances.  The domain controller can also interact with the host controllers on each machine to
  manage the cluster.  To reduce the number of running process, a domain controller also acts as a host controller on
  the machine it runs on.

domain profile::
  A domain profile is a named set of configuration that can be used by a server to boot from.  A domain controller
  can define multiple domain profiles that are consumed by different servers.

server group::
  A server group is a collection of servers.  They are managed and configured as one.  You can assign a domain profile to a server group and every service in that
  group will use that domain profile as their configuration.

In domain mode, a domain controller is started on a master node.  The configuration for the cluster resides in the domain controller.
Next a host controller is started on each machine in the cluster.  Each host controller deployment configuration specifies how
many {{book.project.name}} server instances will be started on that machine.  When the host controller boots up, it starts
as many {{book.project.name}} server instances as it was configured to do.  These server instances pull their configuration
from the domain controller.

==== Domain Configuration

Various other chapters in this guide walk you through configuring various aspects like databases,
HTTP network connections, caches, and other infrastructure related things.  While standalone mode uses the _standalone.xml_ file to configure these things,
domain mode uses the _.../domain/domain.xml_ configuration file.  This is
where the domain profile and server group for the {{book.project.name}} server are defined.


.domain.xml
image:../../{{book.images}}/domain-file.png[]

NOTE: Any changes you make to this file while the domain controller is running will not take effect and may even be overwritten
      by the server.  Instead use the the command line scripting or the web console of {{book.appserver.name}}.  See
      the link:{{book.appserver.admindoc.link}}[{{book.appserver.admindoc.name}}] for more information.

Let's look at some aspects of this _domain.xml_ file.  The +auth-server+ +profile+ XML block is where you are going to make the bulk of your configuration decisions.
You'll be configuring things here like network connections, caches, and database connections.


.auth-server profile
[source,xml]
----
    <profiles>
        <profile name="auth-server">
           ...
        </profile>
----

The +ha-sockets+ +socket-binding-group+ defines the default port mappings for various connectors that are opened with each
{{book.project.name}} server instance.  Any value that contains +${...}+ is a value that can be overriden on the command line
with the +-D+ switch, i.e.

----
$ domain.sh -Djboss.http.port=80
----

The definition of the server group for {{book.project.name}} resides in the +server-groups+ XML block.  It specifies the domain profile
that is used (+default+) and also some default boot arguments for the Java VM when the host controller boots an instance.  It also
binds a +socket-binding-group+ to the server group.

.server group
[source,xml]
----
    <server-groups>
        <server-group name="auth-server-group" profile="auth-server">
            <jvm name="default">
                <heap size="64m" max-size="512m"/>
            </jvm>
            <socket-binding-group ref="ha-sockets"/>
        </server-group>
    </server-groups>
----



==== Host Controller Configuration

{{book.project.name}} comes with two host controller configuration files that reside in the _.../domain/configuration/_ directory:
_host-master.xml_ and _host-slave.xml_.  _host-master.xml_ is configured to boot up a domain controller, a load balancer, and
one {{book.project.name}} server instance.  _host-slave.xml_ is configured to talk to the domain controller and boot up
one {{book.project.name}} server instance.

NOTE:  You should remove the load balancer server from _host-master.xml_.  The load balancer included is really not that
       production ready and doesn't work as smoothly as something like Apache HTTPD + mod-cluster or a hardward based one.

.Host Controller Config
image:../../{{book.images}}/host-files.png[]

To disable the load balancer server instance, edit _host-master.xml_ and comment out or remove the +"load-balancer"+ entry.

[source,xml]
----
    <servers>
        <!-- remove or comment out next line -->
        <server name="load-balancer" group="loadbalancer-group"/>
        ...
    </servers>
----

Another interesting thing to note about this file is the declaration of the authentication server instance.  It has
a +port-offset+ setting.  Any network port defined in the _domain.xml_ +socket-binding-group+ or the server group
will have the value of +port-offset+ added to it.  For this example domain setup we do this so that ports opened by
the load balancer server don't conflict with the authentication server instance that is started.

[source,xml]
----
    <servers>
        ...
        <server name="server-one" group="auth-server-group">
             <socket-bindings port-offset="150"/>
        </server>
    </servers>
----

==== Server Instance Working Directories

Each {{book.project.name}} server instance defined in your host files creates a working directory under _.../domain/servers/{SERVER NAME}_.
Additional configuration can be put there, and any temporary, log, or data files the server instance needs or creates go there too.
The structure of these per server directories ends up looking like any other {{book.appserver.name}} booted server.

.Working Directories
image:../../{{book.images}}/domain-server-dir.png[]

==== {{book.project.name}} JSon Configuration

Unfortunately, there is no centralized way to manage the _keycloak.json_ file.  You'll have to manage a copy of this file
in every server instance you deploy.  This file must exist in the _.../domain/servers/{SERVER NAME}/configuration directory.

.JSON Configuration
image:../../{{book.images}}/domain-json-config.png[]


==== Domain Boot Script

When running the server in domain mode, there is a specific script you need to run to boot the server depending on your
operating system.  These scripts live in the _bin/_ directory of the server distribution.

.Standalone Boot Scripts
image:../../{{book.images}}/domain-boot-files.png[]

To boot the server:

.Linux/Unix
[source]
----
$ .../bin/domain.sh --host-config=host-master.xml
----

.Windows
[source]
----
> ...\bin\domain.bat --host-config=host-slave.xml
----

When running the boot script you will need pass in the host controlling configuration file you are going to use via the
+--host-config+ switch.


==== Running the Clustered Domain Example

The example domain that comes with {{book.project.name}} was meant to run on one machine.  It starts a:
* domain controller
* HTTP load balancer
* 2 {{book.project.name}} server instances

To simulate running a cluster on two machines, you'll run the +domain.sh+ script twice to start two separate
host controllers.  The first will be the master host controller.  It start a domain controller, an HTTP load balancer, and one
{{book.project.name}} authentication server instance.  The second will be a slave host controller that only starts
up an authentication server instance.

===== Setup Secure Master Slave Connection

Before you can boot things up though, you have to configure the slave host controller so that it can talk securely to the domain
controller to obtain the centralized configuration.  To set up a secure connection, you have to create a server admin user and a secret that
will be shared between the master and the slave.  You do this by running the +.../bin/add-user.sh+ script.

When you run the script select +Management User+ and answer +yes+ when it asks you if the new user is going to be used
for one AS process to connect to another.  This will generate a secret that you'll need to cut and paste into the
_.../domain/configuration/host-slave.xml_ file.

.Add App Server Admin
[source,shell]
----
$ add-user.sh
 What type of user do you wish to add?
  a) Management User (mgmt-users.properties)
  b) Application User (application-users.properties)
 (a): a
 Enter the details of the new user to add.
 Using realm 'ManagementRealm' as discovered from the existing property files.
 Username : admin
 Password recommendations are listed below. To modify these restrictions edit the add-user.properties configuration file.
  - The password should not be one of the following restricted values {root, admin, administrator}
  - The password should contain at least 8 characters, 1 alphabetic character(s), 1 digit(s), 1 non-alphanumeric symbol(s)
  - The password should be different from the username
 Password :
 Re-enter Password :
 What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[ ]:
 About to add user 'admin' for realm 'ManagementRealm'
 Is this correct yes/no? yes
 Added user 'admin' to file '/.../standalone/configuration/mgmt-users.properties'
 Added user 'admin' to file '/.../domain/configuration/mgmt-users.properties'
 Added user 'admin' with groups to file '/.../standalone/configuration/mgmt-groups.properties'
 Added user 'admin' with groups to file '/.../domain/configuration/mgmt-groups.properties'
 Is this new user going to be used for one AS process to connect to another AS process?
 e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls.
 yes/no? yes
 To represent the user add the following to the server-identities definition <secret value="bWdtdDEyMyE=" />
----

Now cut and paste the secret value into the .../domain/configuration/host-slave.xml_ file:

[source,xml]
----
     <management>
         <security-realms>
             <security-realm name="ManagementRealm">
                 <server-identities>
                     <secret value="bWdtdDEyMyE="/>
                 </server-identities>
----

===== Run the Boot Scripts

Since we're simulating running on two separate machines, you'll run the boot script twice:

.Boot up master
[source,shell]
----
$ domain.sh --host-config=host-master.xml
----

.Boot up slave
[source,shell]
----
$ domain.sh --host-config=host-slave.xml
----

To try it out, open your browser and go to http://localhost:8080/auth