diff --git a/SUMMARY.adoc b/SUMMARY.adoc index 0cff7918d0..6c3b58982a 100755 --- a/SUMMARY.adoc +++ b/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] diff --git a/images/domain.png b/images/domain.png new file mode 100755 index 0000000000..6a751437d0 Binary files /dev/null and b/images/domain.png differ diff --git a/keycloak-images/domain-boot-files.png b/keycloak-images/domain-boot-files.png new file mode 100755 index 0000000000..0b6b33415c Binary files /dev/null and b/keycloak-images/domain-boot-files.png differ diff --git a/keycloak-images/domain-file.png b/keycloak-images/domain-file.png new file mode 100755 index 0000000000..7cc58397f6 Binary files /dev/null and b/keycloak-images/domain-file.png differ diff --git a/keycloak-images/host-files.png b/keycloak-images/host-files.png new file mode 100755 index 0000000000..dbab3fa68b Binary files /dev/null and b/keycloak-images/host-files.png differ diff --git a/rhsso-images/domain-boot-files.png b/rhsso-images/domain-boot-files.png new file mode 100755 index 0000000000..b62910ecde Binary files /dev/null and b/rhsso-images/domain-boot-files.png differ diff --git a/rhsso-images/domain-file.png b/rhsso-images/domain-file.png new file mode 100755 index 0000000000..f8e6f48221 Binary files /dev/null and b/rhsso-images/domain-file.png differ diff --git a/rhsso-images/host-files.png b/rhsso-images/host-files.png new file mode 100755 index 0000000000..77dddb3c1c Binary files /dev/null and b/rhsso-images/host-files.png differ diff --git a/topics/installation/system-requirements.adoc b/topics/installation/system-requirements.adoc index 6f741396f7..49b2a3f1ef 100755 --- a/topics/installation/system-requirements.adoc +++ b/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 <> 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 <> 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 <> section of this guide for more information. \ No newline at end of file diff --git a/topics/operating-mode/domain-example.adoc b/topics/operating-mode/domain-example.adoc new file mode 100755 index 0000000000..50148ef67a --- /dev/null +++ b/topics/operating-mode/domain-example.adoc @@ -0,0 +1,6 @@ +== Domain Mode Example Walkthrough + +As noted in the <> 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. \ No newline at end of file diff --git a/topics/operating-mode/domain.adoc b/topics/operating-mode/domain.adoc new file mode 100755 index 0000000000..93e0a612fa --- /dev/null +++ b/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] +---- + + + ... + +---- + +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] +---- + + + + + + + + +---- + +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. + + + + + + + + diff --git a/topics/operating-mode/standalone-ha.adoc b/topics/operating-mode/standalone-ha.adoc index dad7f8e588..d3f5607db6 100755 --- a/topics/operating-mode/standalone-ha.adoc +++ b/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 <> and +<> sections of this guide walk you though these things. .Standalone HA Config image:../../{{book.images}}/standalone-ha-config-file.png[] diff --git a/topics/operating-mode/standalone.adoc b/topics/operating-mode/standalone.adoc index 4444bcd68f..986b879d5b 100755 --- a/topics/operating-mode/standalone.adoc +++ b/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 diff --git a/topics/overview.adoc b/topics/overview.adoc index 82e921621c..d6ae0e5945 100755 --- a/topics/overview.adoc +++ b/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. +