2nd draft

SUMMARY.adoc

@@ -1,6 +1,5 @@
 = Summary
 
- . link:topics/preface.adoc[Preface]
  . link:topics/overview.adoc[Overview]
  .. link:topics/overview/recommended-reading.adoc[Recommended Reading]
  . link:topics/installation.adoc[Installation]

book.json

@@ -13,8 +13,8 @@
     "product": false,
     "images": "keycloak-images",
     "appserver": {
-      "name": "JBoss EAP",
+      "name": "Wildfly",
-      "version": "6.4",
+      "version": "10",
       "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/"
@@ -57,6 +57,11 @@
         "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"
       }
 
+    },
+    "developerguide": {
+      "name": "Keycloak Server Developer Guide",
+      "link": "https://keycloak.gitbooks.io/server-developer-guide/content/"
+
     },
     "adminguide": {
       "name": "Keycloak Adminstration Guide",

topics/database/datasource.adoc

@@ -1,8 +1,8 @@
 === Modify the {{book.project.name}} Datasource
 
 After declaring your JDBC driver, you  have to modify the existing datasource configuration that {{book.project.name}} uses
-to connect to the built-in embedded database.  You'l need to change it to connect to your new external database.  You'll do
+to connect it to your new external database.  You'll do
-this within the same configuration file and XML block that you registered your JDBC driver.  Here's an example
+this within the same configuration file and XML block that you registered your JDBC driver in.  Here's an example
 that set's up the connection to your new database:
 
 .Declare Your JDBC Drivers
@@ -27,8 +27,8 @@ that set's up the connection to your new database:
   </subsystem>
 ----
 
-Search for the +datasource+ definition for +KeycloakDS+.  You'll first need to specify the +connection-url+.  The
+Search for the +datasource+ definition for +KeycloakDS+.  You'll first need to modify the +connection-url+.  The
-documentation for your vendor's JDBC implementation will tell you the connection URL you should provide there.
+documentation for your vendor's JDBC implementation should specify the format for this connection URL value.
 
 Next define the +driver+ you will use.  This is the logical name of the JDBC driver you declared in the previous section of this
 chapter.
@@ -37,10 +37,10 @@ It is expensive to open a new connection to a database ever time you want to per
 implementation maintains a pool of open connections.  The +max-pool-size+ specifies the maximum number of connections it will pool.
 You may want to change the value of this depending on the load of your system.
 
-Finally, or PostgreSQL at least, you need to define the database username and password that is needed to connect to the database.  You
+Finally, with PostgreSQL at least, you need to define the database username and password that is needed to connect to the database.  You
 may be worried that this is in clear text in the example.  There are methods to obfuscate this, but this is beyond the
 scope of this guide.
 
 NOTE:  For more information and details features of datasources, please see the link:{{book.appserver.datasource.link}}[the datasource configuration chapter]
-of the {{book.appserver.admindoc.name}}.
+       of the {{book.appserver.admindoc.name}}.
 

topics/database/hibernate.adoc

@@ -1,7 +1,7 @@
 === Hibernate Configuration
 
-The Hibernate persistence API is already pre-configured out of the box.  It is rare to have to modify the configuration for it.
+The Hibernate persistence API is already pre-configured out of the box and rarely needs to be changed.
-To configure Hibernate, you need to edit the _keycloak-server.json_ file.  If you are running
+The configuration for this component lies in the _keycloak-server.json_ file.  If you are running
 in standalone mode, this file is in the _.../standalone/configuration_ directory.  If you are running in domain mode
 this file will live in the _.../domain/servers/{server name}/configuration_ directory.
 

topics/database/jdbc.adoc

@@ -1,13 +1,14 @@
 === Package the JDBC Driver
 
-Find and download the JDBC driver JAR for your RDBMS.  Before you can use this driver, you must package it up into a module.
+Find and download the JDBC driver JAR for your RDBMS.  Before you can use this driver, you must package it up into a module
+and install it into the server.
 Modules define JARs that are loaded into the {{book.project.name}} classpath and the dependencies those JARs have on
 other modules.  They are pretty simple to set up.
 
 Within the _.../modules/system/layers/keycloak/_ directory of your
 {{book.project.name}} distribution, you need to create a directory structure to hold your module definition.  The convention is use the Java package name
 of the JDBC driver for the name of the directory structure.  For PostgreSQL, create the directory _org/postgresql/main_.  Copy your database
-driver JAR into this directory and also create an empty _module.xml_ file.
+driver JAR into this directory and create an empty _module.xml_ file within it too.
 
 .Module Directory
 image:../../{{book.images}}/db-module.png[]
@@ -32,28 +33,20 @@ After you have done this, open up the _module.xml_ file and create the following
 ----
 
 The module name should match the directory structure of your module.  So, _org/postgresql_ maps to +org.postgresql+.  The
-+resource-root path+ attribute should specify the JAR filename.  The rest are just the normal dependencies that
++resource-root path+ attribute should specify the JAR filename of the driver.  The rest are just the normal dependencies that
 any JDBC driver JAR would have.
 
 === Declare and Load JDBC Driver
 
 The next thing you have to do is declare your newly packaged JDBC driver into your deployment profile so that it loads and becomes
-available.  Where you perform this action depends on your <<fake/../operating-mode.adoc#_operating-mode,operating mode>>.  If you're
+available when the server boots up.  Where you perform this action depends on your <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>.  If you're
 deploying in standard mode, edit _.../standalone/configuration/standalone.xml_.  If you're deploying in standard clustering
 mode, edit _.../standalone/configuration/standalone-ha.xml_.  If you're deploying in domain mode, edit
-_.../domain/configuration/domain.xml_.  In domain mode, you'll need to make sure you edit the profile you are using:
+_.../domain/configuration/domain.xml_.  In domain mode, you'll need to make sure you edit the profile you are using: either
 +auth-server-standalone+ or +auth-server-clustered+
 
-.Domain Profile
-[source,xml]
-----
-   <profile name="auth-server-clustered">
-      ...
-   </profile>
-----
-
 Within the profile, search for the +drivers+ XML block within the +datasources+ subsystem.  You should see
-a pre-defined driver declared for the H2 JDBC driver.  There is where you'll declare the JDBC driver for your external
+a pre-defined driver declared for the H2 JDBC driver.  This is where you'll declare the JDBC driver for your external
 database.
 
 .JDBC Drivers
@@ -72,7 +65,8 @@ database.
 ----
 
 Within the +drivers+ XML block you'll need to declare an additional JDBC driver.  It needs to have a +name+ which
-you can choose to be anything you want.  You have to define the module the new JDBC driver classes are defined in.  Finally
+you can choose to be anything you want.  You specify the +module+ attribute which points to the +module+ package you
+created earlier for the driver JAR.  Finally
 you have to specify the driver's Java class.  Here's an example of installing PostgreSQL driver that lives in the module
 example defined earlier in this chapter.
 

topics/installation.adoc

@@ -1,5 +1,4 @@
 == Installation
 
-This chapter reviews what binaries you need to install to run the {{book.project.name}} Server on a specific machine.
+Installing {{book.project.name}} is as simple as downloading it and unzipping it.  This chapter reviews system requirements
-It describes the directory structure and files of the distribution.  Finally, it describes how to install {{book.project.name}}
+as well as the directory structure of the distribution.
-on the cloud if you prefer that type of deployment.

topics/installation/directory-structure.adoc

@@ -11,20 +11,20 @@ _bin/_::
   This contains various scripts to either boot the server or perform some other management action on the server.
 
 _domain/_::
-  This contains configuration files and working directory when running {{book.project.name}} in <<fake/../../domain-mode.adoc#,domain mode>>.
+  This contains configuration files and working directory when running {{book.project.name}} in <<fake/../../operating-mode/domain.adoc#_domain-mode,domain mode>>.
 
 _modules/_::
   These are all the Java libraries used by the server.
 
 _providers/_::
-  If you are writing extensions to keycloak, you can put your extensions here.  See the link:http://not-implemented-yet[Server Developer Guide] for more information on this.
+  If you are writing extensions to keycloak, you can put your extensions here.  See the link:{{book.developerguide.link}}[{{book.developerguide.name] for more information on this.
 
 _standalone/_::
-  This contains configuration files and working directory when running {{book.project.name}} in <<fake/../../standalone-mode.adoc#,standalone mode>>.
+  This contains configuration files and working directory when running {{book.project.name}} in <<fake/../../operating-mode/standalone.adoc#_standalone-mode,standalone mode>>.
 
 _themes/_::
   This directory contains all the html, style sheets, javascript files, and images used to display any UI screen displayed by the server.
-  Here you can modify an existing theme or create your own.  See the link:http://not-implemented-yet[Server Developer Guide] for more information on this.
+  Here you can modify an existing theme or create your own.  See the link:{{book.developerguide.link}}[{{book.developerguide.name] for more information on this.
 
 
 

topics/installation/distribution-files-community.adoc

@@ -10,13 +10,13 @@ The 'keycloak-{{book.project.version}}.[zip|tar.gz]' file is the server only dis
 to run the Keycloak Server.  To unpack this file just run your operating system's +unzip+ or +gunzip+ and +tar+ utilities.
 
 The 'keycloak-overlay-{{book.project.version}}.[zip|tar.gz]' file is a Wildfly Service Pack that allows you to install Keycloak Server on top of an existing
-Wildfly or JBoss EAP distribution.  We suggest that you do not use this file unless you want to install on top of a JBoss EAP distribution.  We do not support
+Wildfly or JBoss EAP distribution.  We suggest that you do not use this distribution unless you want to install on top of the latest JBoss EAP distribution.  We do not support
 users that want to run their applications and Keycloak on the same server instance.  To install the Keycloak Service Pack, just unzip it in the root directory
 of your JBoss EAP distribution.
 
-The 'keycloak-demo-{{book.project.version}}.[zip|tar.gz]' contains a the server binaries, all documentation and all examples.  It is preconfigured with both the
+The 'keycloak-demo-{{book.project.version}}.[zip|tar.gz]' contains the server binaries, all documentation and all examples.  It is preconfigured with both the
 OIDC and SAML client application adapters and can deploy any of the distribution examples out of the box with no configuration.  This distribution is only
-recommended for those that want to test drive Keycloak.
+recommended for those that want to test drive Keycloak.  We do not support users that run the demo distribution in production.
 
 To unpack of these files run the +unzip+ or +gunzip+ and +tar+ utilities.
 

topics/installation/distribution-files-product.adoc

@@ -1,11 +1,11 @@
 === Installing Distribution Files
 
-The Keycloak Server is contained in one distribution file:
+The {{book.project.name}} Server is contained in one distribution file:
 
 * 'RH-SSO-{{book.project.version}}.[zip|tar.gz]'
 
 The 'RH-SSO-{{book.project.version}}.[zip|tar.gz]' file is the server only distribution.  It contains nothing other than the scripts and binaries
-to run the Keycloak Server.
+to run the {{book.project.name}} Server.
 
 To unpack of these files run the +unzip+ or +gunzip+ and +tar+ utilities.
 

topics/installation/system-requirements.adoc

@@ -7,9 +7,9 @@ These are the requirements to run the {{book.project.name}} authentication serve
 * zip or gzip and tar
 * 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.
+* Network multicast support on your machine if you want to run in a cluster.  {{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.adoc

@@ -4,8 +4,7 @@
 
 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 operating mode comes in.  This decision
+your server configurations?  Your choice of operating mode effects how you configure databases, configure caching and even how you boot the server.
- 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

topics/operating-mode/domain.adoc

@@ -1,6 +1,8 @@
 [[_domain-mode]]
 === Domain Clustered Mode
 
+Domain mode is a way to centrally manage and publish the configuration for your servers.
+
 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.
@@ -46,11 +48,11 @@ where the domain profile and server group for the {{book.project.name}} server a
 .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
+WARNING: 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.
+Let's look at some aspects of this _domain.xml_ file.  The +auth-serve-standalone+ and +auth-server-clustered+ +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.
 
 
@@ -58,12 +60,36 @@ You'll be configuring things here like network connections, caches, and database
 [source,xml]
 ----
     <profiles>
-        <profile name="auth-server">
+        <profile name="auth-server-standalone">
+            ...
+         </profile>
+       <profile name="auth-server-clustered">
            ...
         </profile>
 ----
 
-The +ha-sockets+ +socket-binding-group+ defines the default port mappings for various connectors that are opened with each
+The +auth-server-standalone+ profile is a non-clustered setup.  The +auth-server-clustered+ profile is the clustered setup.
+
+If you scroll down further, you'll see various +socket-binding-groups+ defined.
+
+.socket-binding-grous
+[source,xml]
+----
+    <socket-binding-groups>
+        <socket-binding-group name="standard-sockets" default-interface="public">
+           ...
+        </socket-binding-group>
+        <socket-binding-group name="ha-sockets" default-interface="public">
+           ...
+        </socket-binding-group>
+        <!-- load-balancer-sockets should be removed in production systems and replaced with a better softare or hardare based one -->
+        <socket-binding-group name="load-balancer-sockets" default-interface="public">
+           ...
+        </socket-binding-group>
+    </socket-binding-groups>----
+
+
+This config 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.
 
@@ -79,7 +105,14 @@ binds a +socket-binding-group+ to the server group.
 [source,xml]
 ----
     <server-groups>
-        <server-group name="auth-server-group" profile="auth-server">
+        <!-- load-balancer-group should be removed in production systems and replaced with a better softare or hardare based one -->
+        <server-group name="load-balancer-group" profile="load-balancer">
+            <jvm name="default">
+                <heap size="64m" max-size="512m"/>
+            </jvm>
+            <socket-binding-group ref="load-balancer-sockets"/>
+        </server-group>
+        <server-group name="auth-server-group" profile="auth-server-clustered">
             <jvm name="default">
                 <heap size="64m" max-size="512m"/>
             </jvm>
@@ -97,8 +130,9 @@ _host-master.xml_ and _host-slave.xml_.  _host-master.xml_ is configured to boot
 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
+NOTE:  The load balancer is not a required service.  It exists so that you can easily test drive clustering on your development
-       production ready and doesn't work as smoothly as something like Apache HTTPD + mod-cluster or a hardward based one.
+       machine.  While usable in production, you have the option of replacing it if you have a different hardware or software
+       based load balancer you want to use.
 
 .Host Controller Config
 image:../../{{book.images}}/host-files.png[]
@@ -152,7 +186,7 @@ image:../../{{book.images}}/domain-json-config.png[]
 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
+.Domain Boot Script
 image:../../{{book.images}}/domain-boot-files.png[]
 
 To boot the server:
@@ -173,22 +207,25 @@ When running the boot script you will need pass in the host controlling configur
 +--host-config+ switch.
 
 [[_clustered-domain-example]]
-==== Running the Clustered Domain Example
+==== Clustered Domain Example
 
-The example domain that comes with {{book.project.name}} was meant to run on one machine.  It starts a:
+You can test drive clustering using the out-of-the-box _domain.xml_ configuration.  This example
-* domain controller
+domain is meant to run on one machine and boots up:
-* HTTP load balancer
+
+* a domain controller
+* an 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
+host controllers.  The first will be the master host controller which will 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
+===== Setup Slave Connection to Domain Controller
 
 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
+controller.  If you do not do this, then the slave host will not be able to obtain the centralized configuration from the domain controller.
+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
@@ -225,7 +262,7 @@ $ add-user.sh
  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:
+Now cut and paste the secret value into the _.../domain/configuration/host-slave.xml_ file as follows:
 
 [source,xml]
 ----
@@ -239,7 +276,7 @@ Now cut and paste the secret value into the _.../domain/configuration/host-slave
 
 ===== Run the Boot Scripts
 
-Since we're simulating running on two separate machines, you'll run the boot script twice:
+Since we're simulating a two node cluster on one development machine, you'll run the boot script twice:
 
 .Boot up master
 [source,shell]

topics/operating-mode/standalone-ha.adoc

@@ -3,14 +3,14 @@
 === 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
+requires that you have a copy of the {{book.project.name}} distribution on each machine you want to run a server instance.
-deploy initially, this mode can become cumbersome if you end up having a large cluster because you will have to
+This mode can be very easy to deploy initially, but can become quite cumbersome. To make a configuration change
-modify the configuration in each node anytime you need to make a change.
+you'll have to modify each distribution on each machine.  For a large cluster this can become time consuming and error prone.
 
 ==== Standalone Clustered Configuration
 
 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
+infrastructure settings for 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
@@ -19,11 +19,11 @@ deploy some type of load balancer in front of the cluster.  The <<fake/../../clu
 .Standalone HA Config
 image:../../{{book.images}}/standalone-ha-config-file.png[]
 
-NOTE: Any changes you make to this file while the server is running will not take effect and may even be overwritten
+WARNING: Any changes you make to this file while the server 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.
 
-==== Standalone Boot Script
+==== Standalone Clustered Boot Script
 
 You use the same boot scripts to start {{book.project.name}} as you do in standalone mode.  The difference is that
 you pass in an additional flag to point to the HA config file.
@@ -48,9 +48,9 @@ $ .../bin/standalone.sh --server-config=standalone-ha.xml
 ==== Standalone Clustered {{book.project.name}} JSON Configuration
 
 The {{book.project.name}} specific json configure file resides in the same place as in standalone mode: _.../standalone/configuration/keycloak.json_.
-Like _standalone-ha.xml_ you have to modify this file in each distribution in your cluster in order for changes to take effect.
+Like _standalone-ha.xml_ you have to modify this file in each distribution in your cluster when you want to make a change here.
 
-NOTE: Any changes you make to this file while the server is running will not take effect.  You'll need to reboot the
+WARNING: Any changes you make to this file while the server is running will not take effect.  You'll need to reboot the
       server.
 
 

topics/operating-mode/standalone.adoc

@@ -2,7 +2,7 @@
 === Standalone Mode
 
 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
+It is not usable for clustered deployments 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}}
 
@@ -37,21 +37,21 @@ derivative of.  In the standalone operation mode, this file lives in _.../standa
 .Standalone Config File
 image:../../{{book.images}}/standalone-config-file.png[]
 
-NOTE: Any changes you make to this file while the server is running will not take effect and may even be overwritten
+WARNING: Any changes you make to this file while the server 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.
 
 
 ==== Standalone {{book.project.name}} JSON Configuration
 
-{{book.project.name}} has a json configuration file that is specific to {{book.project.name}} this is located within
+{{book.project.name}} has a json configuration file that is specific to {{book.project.name}} components.  This configuration is located within
-_.../standalone/configuration/keycloak.json_.  This file is used to configure non-infrastructure level things that are
+the file_.../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
 image:../../{{book.images}}/standalone-json-config-file.png[]
 
-NOTE: Any changes you make to this file while the server is running will not take effect.  You'll need to reboot the
+WARNING: Any changes you make to this file while the server is running will not take effect.  You'll need to reboot the
       server.
 
 

topics/overview/recommended-reading.adoc

@@ -6,5 +6,5 @@ goes over the basics for infrastructure-level configuration.  It is highly recom
 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.caching.admindoc.link}}[{{book.caching.admindoc.name}}]
-* link:{{book.jpa.admindoc.link}}[{{book.jpa.admindoc.name}}]
+* link:{{book.jpa.admindoc.link}}[Hibernate JPA Configuration]

topics/preface.adoc

@@ -1,22 +0,0 @@
-
-== Preface
-
-In some of the example listings, what is meant to be displayed on one line does not fit inside the available page width.These lines have been broken up. A '\' at the end of a line means that a break has been introduced to fit in the page, with the following lines indented.
-So: 
-[source]
-----
-Let's pretend to have an extremely \
-long line that \
-does not fit
-This one is short
-----         
-Is really: 
-
-[source]
-----
-Let's pretend to have an extremely long line that does not fit
-This one is short
-----
-
-
-