more

SUMMARY.adoc

@@ -16,6 +16,8 @@
  . link:topics/operating-mode.adoc[Choosing an Operating Mode]
  .. link:topics/operating-mode/standalone.adoc[Standalone Mode]
  .. link:topics/operating-mode/standalone-ha.adoc[Standalone Clustered Mode]
+ .. link:topics/operating-mode/domain.adoc[Domain Clustered Mode]
+ .. link:topics/operating-mode/domain-example.adoc[Domain Clustered Mode]
  . link:topics/cache.adoc[Server Cache]
  . link:topics/clustering.adoc[Clustering]
  . link:topics/proxy.adoc[Keycloak Security Proxy]

topics/installation/system-requirements.adoc

@@ -5,9 +5,11 @@ These are the requirements to run the {{book.project.name}} authentication serve
 * Can run on any operating system that runs Java
 * Java 8 JDK
 * zip or gzip and tar
-* Network multicast support if you are clustering {{book.project.name}}.
 * At least 512M of RAM
 * At least 1G of diskspace
+* Network multicast support on your machine if you want to run in a cluster out of the box.  {{book.project.name}} can
+ be clustered without multicast, but this requires a bunch of configuration changes.  Please see
+ the <<fake/../../clustering.adoc#_clustering,clustering>> section of this guide for more information.
+* A shared external database like Postgres, MySql, Oracle, etc.  {{book.project.name}} requires an external shared
+  database if you want to run in a cluster.   Please see the <<fake/../../database.adoc#_database,database configuration>> section of this guide for more information.
 
-{{book.project.name}} can be clustered without multicast, but this requires a bunch of configuration changes.  Please see
-the <<fake/../../clustering.adoc#_clustering,clustering>> section of this guide for more information.

topics/operating-mode/domain-example.adoc

@@ -0,0 +1,6 @@
+== Domain Mode Example Walkthrough
+
+As noted in the <<domain.adoc#,domain mode>> chapter, {{book.project.name}} comes with a mostly pre-configured clustered domain
+setup.  This chapter walks you through this out of the box configuration highlighting each aspect of each configuration
+file you need to touch and manage.  At the end, the chapter discusses what changes you'll need to make to this out of the
+box configuration to have it work in a real cluster.

topics/operating-mode/domain.adoc

@@ -0,0 +1,126 @@
+[[_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.
+
+{{book.project.name}} does come with a pre-configured _domain.xml_ file.  While it will work almost out of the box, there is some tweaks you need
+to make to it for it to be able to manage a real cluster.  The <<_example_domain,example domain>> section of this chapter walks through each
+aspect of this pre-configured _domain.xml_ file.
+
+.domain.xml
+image:../../{{book.images}}/domain-file.png[]
+
+The default +profile+ XML block is where you are going to make the bulk of your configuration decisions.  You can edit this file
+directly prior to booting the domain controller, but you should use the {{book.appserver.name}} web console or command line interface
+to modify it at runtime.
+
+.profile
+[source,xml]
+----
+    <profiles>
+        <profile name="default">
+           ...
+        </profile>
+----
+
+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 so default boot arguments for the Java VM when the host controller boots an instance.
+
+.server group
+[source,xml]
+----
+    <server-groups>
+        <server-group name="main-server-group" profile="default">
+            <jvm name="default">
+                <heap size="64m" max-size="512m"/>
+            </jvm>
+            <socket-binding-group ref="standard-sockets"/>
+        </server-group>
+    </server-groups>
+----
+
+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.
+
+==== 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.
+
+.Host Controller Config
+image:../../{{book.images}}/host-files.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.
+
+
+
+
+
+
+
+

topics/operating-mode/standalone-ha.adoc

@@ -1,4 +1,6 @@
-=== Standalone Clustered
+[[_standalone-ha-mode]]
+
+=== Standalone Clustered Mode
 
 Standalone clustered operation mode is for when you want to run {{book.project.name}} within a cluster.  This mode
 requires that you have a copy of each distribution for each node you want to run in the cluster.  While very easy to
@@ -7,9 +9,12 @@ modify the configuration in each node anytime you need to make a change.
 
 ==== Standalone Clustered Configuration
 
-The distribution has a pre-configured app server configuration file for running within a cluster.  It has all the specific
-infrasture settings you need for the clustered caches and discovery that {{book.project.name}} needs.  This file resides
-in _.../standalone/configuration/standalone-ha.xml_
+The distribution has a mostly pre-configured app server configuration file for running within a cluster.  It has all the specific
+infrasture settings you need to configure networking, databases, caches, and discovery.  This file resides
+in _.../standalone/configuration/standalone-ha.xml_.  There's a few things missing from this configuration.
+You can't run {{book.project.name}} in a cluster without a configuring a shared database connection.  You also need to
+deploy some type of load balancer in front of the cluster.  The <<fake/../../clustering.adoc#_clustering,clustering>> and
+<<fake/../../database.adoc#_database,database>> sections of this guide walk you though these things.
 
 .Standalone HA Config
 image:../../{{book.images}}/standalone-ha-config-file.png[]

topics/operating-mode/standalone.adoc

@@ -1,11 +1,10 @@
 [[_standalone-mode]]
 === Standalone Mode
 
-Standalone operating mode is only useful when you want to run one, and only one {{book.project.name}} server instance.  Standalone
-instances contain all the configuration files they need locally.  What this basically means is that any configuration done
-must be done on the config files contained in the installed distribution on the machine the {{book.project.name}} is going to run on
-{{book.project.name}} standalone mode is available pre-configured out of the box.  It turns off clustering entirely
-and turns any distributed caches into local-only ones.
+Standalone operating mode is only useful when you want to run one, and only one {{book.project.name}} server instance.
+It cannot be made to run in a cluster and all caches are non-distributed and local-only.  It is not recommended that
+you use standalone mode in production as you will have a single point of failure.  If your standalone mode server goes down,
+users will not be able to log in.  This mode is really only useful to test drive and play with the features of {{book.project.name}}
 
 ==== Standalone Boot Script
 

topics/overview.adoc

@@ -8,3 +8,7 @@ own embedded and local-only database.  For
  and finally set up {{book.project.name}} to run in a cluster.  This guide walks through each and every aspect of any pre-boot
  decisions and setup you must do prior to deploying the server.
 
+One thing to particularly note is that {{book.project.name}} is derived from the {{book.appserver.name}} Application Server.
+Many aspects of configuring a {{book.project.name}} revolve around {{book.appserver.name}} configuration elements.  Often
+this guide will direct you to documentation outside of the manual if you want to dive into more detail.
+