diff --git a/SUMMARY.adoc b/SUMMARY.adoc index b59b1656b0..64cd39a1f2 100755 --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -2,6 +2,7 @@ . link:topics/preface.adoc[Preface] . link:topics/overview.adoc[Overview] + . link:topics/overview/recommended-reading.adoc[Recommended Reading] . link:topics/installation.adoc[Installation] .. link:topics/installation/system-requirements.adoc[System Requirements] {% if book.community %} @@ -12,7 +13,7 @@ {% endif %} .. link:topics/installation/directory-structure.adoc[Distribution Directory Structure] .. link:topics/openshift.adoc[Installing on OpenShift] - . link:topics/deployment-mode.adoc[Choosing a Deployment Mode] + . link:topics/deployment-mode.adoc[Choosing an Operation Mode] .. link:topics/deployment-mode/standalone.adoc[Standalone Mode] . link:topics/cache.adoc[Server Cache] . link:topics/clustering.adoc[Clustering] diff --git a/book.json b/book.json index 67fbccc5ac..bef1d07e2f 100755 --- a/book.json +++ b/book.json @@ -15,8 +15,27 @@ "appserver": { "name": "JBoss EAP", "version": "6.4", - "admindoc": "Administration and Configuration Guide", - "admindoclink": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/" + "admindoc": { + "name": "JBoss EAP Administration and Configuration Guide", + "link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Administration_and_Configuration_Guide/" + } + }, + "caching": { + "name": "JBoss Data Grid", + "version": "???", + "admindoc": { + "name": "JBoss Data Grid Administration and Configuration Guide", + "link": "https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.6/html/Administration_and_Configuration_Guide/index.html" + } + }, + "jpa": { + "name": "Hibernate", + "version": "???", + "admindoc": { + "name": "Hibernate Config", + "link": "https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/6.4/html/Development_Guide/sect-Java_Persistence_API_JPA.html#sect-Configuration2" + } + }, "project": { "name": "Keycloak", diff --git a/keycloak-images/standalone-config-file.png b/keycloak-images/standalone-config-file.png new file mode 100755 index 0000000000..8f43a7f55c Binary files /dev/null and b/keycloak-images/standalone-config-file.png differ diff --git a/keycloak-images/standalone-json-config-file.png b/keycloak-images/standalone-json-config-file.png new file mode 100755 index 0000000000..39ea3bfdf2 Binary files /dev/null and b/keycloak-images/standalone-json-config-file.png differ diff --git a/rhsso-images/standalone-config-file.png b/rhsso-images/standalone-config-file.png new file mode 100755 index 0000000000..d77a81b82a Binary files /dev/null and b/rhsso-images/standalone-config-file.png differ diff --git a/rhsso-images/standalone-json-config-file.png b/rhsso-images/standalone-json-config-file.png new file mode 100755 index 0000000000..2f25f3c1ba Binary files /dev/null and b/rhsso-images/standalone-json-config-file.png differ diff --git a/topics/deployment-mode/standalone.adoc b/topics/deployment-mode/standalone.adoc deleted file mode 100755 index 942244dade..0000000000 --- a/topics/deployment-mode/standalone.adoc +++ /dev/null @@ -1,20 +0,0 @@ -=== Standalone Mode - -Standalone 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 Boot Script - -When running the server in standalone 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 -{% if book.product %} -image:../../rhsso-images/standalone-boot-files.png[] -{% endif %} -{% if book.community %} -image:../../keycloak-images/standalone-boot-files.png[] -{% endif %} diff --git a/topics/installation/system-requirements.adoc b/topics/installation/system-requirements.adoc index 05242d261b..69054b7ee3 100755 --- a/topics/installation/system-requirements.adoc +++ b/topics/installation/system-requirements.adoc @@ -10,4 +10,4 @@ These are the requirements to run the {{book.project.name}} authentication serve * At least 1G of diskspace {{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 +the <> section of this guide for more information. \ No newline at end of file diff --git a/topics/deployment-mode.adoc b/topics/operating-mode.adoc similarity index 65% rename from topics/deployment-mode.adoc rename to topics/operating-mode.adoc index c9c92f4a79..9d27b3947b 100755 --- a/topics/deployment-mode.adoc +++ b/topics/operating-mode.adoc @@ -1,10 +1,10 @@ -== Choosing a Deployment Mode +== Choosing an Operating Mode -Before deploying {{book.project.name}} in a production environment you need to decide which type of deployment method +Before deploying {{book.project.name}} in a production environment you need to decide which type of operating mode you are going to use. Will you run {{book.project.name}} within a cluster? Do you want a centralized way to manage -your server configurations? This is where deciding the deployment mode comes in. This decision +your server configurations? This is where deciding the operating mode comes in. This decision effects how you configure databases, configure caching and even how you boot the server. TIP: The {{book.project.name}} is built on top of the {{book.appserver.name}} Application Server. This guide will only go over the basics for deployment within a specific mode. If you want specific information on this, a better place - to go would be the link:{{book.appserver.admindoclink}}[{{book.appserver.admindoc}}] \ No newline at end of file + to go would be the link:{{book.appserver.admindoc.link}}[{{book.appserver.admindoc.name}}] \ No newline at end of file diff --git a/topics/operating-mode/standalone.adoc b/topics/operating-mode/standalone.adoc new file mode 100755 index 0000000000..5e3720c3f7 --- /dev/null +++ b/topics/operating-mode/standalone.adoc @@ -0,0 +1,69 @@ +=== 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 Boot Script + +When running the server in standalone 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 +{% if book.product %} +image:../../rhsso-images/standalone-boot-files.png[] +{% endif %} +{% if book.community %} +image:../../keycloak-images/standalone-boot-files.png[] +{% endif %} + +To boot the server: + +.Linux/Unix +[source] +---- +$ .../bin/standalone.sh +---- + +.Windows +[source] +---- +> ...\bin\standalone.bat +---- + +==== Standalone Configuration + +The bulk of this guide walks you through how to configure infrastructure level aspects of {{book.project.name}}. These +aspects are configured in a configuration file that is specific to the application server that {{book.project.name}} is a +derivative of. In the standalone operation mode, this file lives in _.../standalone/configuration/standalone.xml_. + +.Standalone Config File +{% if book.product %} +image:../../rhsso-images/standalone-config-file.png[] +{% endif %} +{% if book.community %} +image:../../keycloak-images/standalone-config-file.png[] +{% endif %} + +==== Standalone {{book.project.name}} Configuration + +{{book.project.name}} has a json configuration file that is specific to {{book.project.name}} this is located within +_.../standalone/configuration/keycloak.json_. This file is used to configure non-infrastructure level things that are +only applicable to {{book.project.name}} + +.Standalone {{book.project.name}} Config File +{% if book.product %} +image:../../rhsso-images/standalone-json-config-file.png[] +{% endif %} +{% if book.community %} +image:../../keycloak-images/standalone-json-config-file.png[] +{% endif %} + + + + + + + diff --git a/topics/overview/recommended-reading.adoc b/topics/overview/recommended-reading.adoc new file mode 100755 index 0000000000..5e3779988d --- /dev/null +++ b/topics/overview/recommended-reading.adoc @@ -0,0 +1,10 @@ +=== Recommended Additional External Documentation + +{{book.project.name}} is built upon a derivative of the {{book.appserver.name}} Application Server and projects embedded +within {{book.appserver.name}} like {{book.cache.name}} (for caching) and Hibernate (for persistence). This guide only +goes over the basics for infrastructure-level configuration. It is highly recommended that you peruse the documentation +for {{book.appserver.name}} and its sub projects. Here are some links to that documentation: + +* link:{{book.appserver.admindoc.link}}[{{book.appserver.admindoc.name}}] +* link:{{book.cache.admindoc.link}}[{{book.cache.admindoc.name}}] +* link:{{book.jpa.admindoc.link}}[{{book.jpa.admindoc.name}}] \ No newline at end of file