diff --git a/SUMMARY.adoc b/SUMMARY.adoc index e127aeb488..d99a958539 100755 --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -18,6 +18,10 @@ .. link:topics/operating-mode/domain.adoc[Domain Clustered Mode] . link:topics/manage.adoc[Managing Config at Runtime] . link:topics/database.adoc[Relational Database Setup] + .. link:topics/checklist.adoc[Setup Checklist] + .. link:topics/jdbc.adoc[JDBC Setup] + .. link:topics/datasource.adoc[Datasource Setup] + .. link:topics/hibernate.adoc[Hibernate Configuration] {% if book.community %} . link:topics/mongo.adoc[Mongo DB Setup] {% endif %} diff --git a/book.json b/book.json index 5dd8eddcf8..a277afeeb1 100755 --- a/book.json +++ b/book.json @@ -36,7 +36,7 @@ "name": "Hibernate", "version": "???", "admindoc": { - "name": "Hibernate Config", + "name": "JBoss Development Guide", "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" } diff --git a/topics/database.adoc b/topics/database.adoc index cf67ab7a6f..f10fc31efb 100755 --- a/topics/database.adoc +++ b/topics/database.adoc @@ -1,62 +1,23 @@ [[_database]] == Relational Database Setup +{{book.project.name}} comes with its own embedded Java-based relational database called H2. +This is the default database that {{book.project.name}} will use to persist data and really only exists so that you can run the authentication +server out of the box. We highly recommend that you replace it with a more production ready external database. The H2 database +is not very viable in high concurrency situations and cannot be used in a cluster either. The purpose of this chapter is to +show you how to connect {{book.project.name}} to a more mature database. -Out of the box, {{book.project.name}} persists its data using the Hibernate JPA set of APIs on top of an embedded Java based relational database. -The built-in database is not viable in high load and high concurrency situations. It cannot be used in a cluster either. It is -highly recommended that you replace the default embedded database with a more scalable and reliable solution like PostgreSQL or MySql. This -chapter will show you how to configure {{book.project.name}} to use an external relational database. It will also discuss -how you can configure the Hibernate JPA persistence abstraction that sits on top of your RDBMS. +{{book.project.name}} uses two layered technologies to persist its relational data. The bottom layered technology is JDBC. JDBC +is a Java API that is used to connect to a RDBMS. There are different JDBC drivers per database type that are provided +by your database vendor. This chapter discusses how to configure {{book.project.name}} to use one of these vendor-specific drivers. -NOTE: Datasource configuration is covered much more thoroughly within the link:{{book.appserver.dataource.link}}[the datasource configuration chapter] +The top layered technology for persistence is Hibernate JPA. This is a object to relational mapping API that maps Java +Objects to relational data. Most deployments of {{book.project.name}} will never have to touch the configuration aspects +of Hibernate, but we will discuss how that is done if you run into that rare circumstance. + +NOTE: Datasource configuration is covered much more thoroughly within the link:{{book.appserver.datasource.link}}[the datasource configuration chapter] of the {{book.appserver.admindoc.name}}. -=== RDBMS Checklist -These are the steps you will need to perform to get an RDBMS configured for {{book.project.name}}. -. Locate and download a JDBC driver for your database -. Package the driver JAR into a module and install this module into the server -. Declare the JDBC driver in the configuration profile of the server -. Modify the datasource configuration to use your database's JDBC driver -. Modify the datasource configuration to define the connection parameters to your database - -This chapter will use PostgresSQL for all its examples. Other databases follow the same steps for installation. - -=== 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. -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. - -.Module Directory -image:../{{book.images}}/db-module.png[] - -After you have done this, open up the _module.xml_ file and create the following XML - -.Module XML -[source,xml] ----- - - - - - - - - - - - - ----- - -The module name should match the directory structure of your module. _org/postgresql_ maps to +org.postgresql+. The -+resource-root path+ attribute should specify the JAR filename. The rest are just the normal dependencies that -any JDBC driver JAR would have. diff --git a/topics/database/checklist.adoc b/topics/database/checklist.adoc new file mode 100755 index 0000000000..d578f89478 --- /dev/null +++ b/topics/database/checklist.adoc @@ -0,0 +1,12 @@ +=== RDBMS Setup Checklist + +These are the steps you will need to perform to get an RDBMS configured for {{book.project.name}}. + +. Locate and download a JDBC driver for your database +. Package the driver JAR into a module and install this module into the server +. Declare the JDBC driver in the configuration profile of the server +. Modify the datasource configuration to use your database's JDBC driver +. Modify the datasource configuration to define the connection parameters to your database + +This chapter will use PostgresSQL for all its examples. Other databases follow the same steps for installation. + diff --git a/topics/database/datasource.adoc b/topics/database/datasource.adoc new file mode 100755 index 0000000000..4f7963b5eb --- /dev/null +++ b/topics/database/datasource.adoc @@ -0,0 +1,46 @@ +=== 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 +this within the same configuration file and XML block that you registered your JDBC driver. Here's an example +that set's up the connection to your new database: + +.Declare Your JDBC Drivers +[source,xml] +---- + + + ... + + jdbc:postgresql://localhost/keycloak + postgresql + + 20 + + + William + password + + + ... + + +---- + +Search for the +datasource+ definition for +KeycloakDS+. You'll first need to specify the +connection-url+. The +documentation for your vendor's JDBC implementation will tell you the connection URL you should provide there. + +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. + +It is expensive to open a new connection to a database ever time you want to perform a transaction. To compensate, the datasource +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 +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}}. + diff --git a/topics/database/hibernate.adoc b/topics/database/hibernate.adoc new file mode 100755 index 0000000000..fe43659b5a --- /dev/null +++ b/topics/database/hibernate.adoc @@ -0,0 +1,52 @@ +=== 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. +To configure Hibernate, you need to edit 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. + +.Hibernate JPA Config +[source,json] +---- +"connectionsJpa": { + "default": { + "dataSource": "java:jboss/datasources/KeycloakDS", + "databaseSchema": "update" + } +}, +---- + +Possible configuration options are: + +dataSource:: + JNDI name of the dataSource + +jta:: + boolean property to specify if datasource is JTA capable + +driverDialect:: + Value of database dialect. + In most cases you don't need to specify this property as dialect will be autodetected by Hibernate. + +databaseSchema:: + Specify if schema should be updated or validated. + Valid values are +update+ (default) and +validate+. The +update+ value will set up or update + the table definitions that {{book.project.name}} needs. +validate+ just makes sure that the database has + the appropriate table definitions set up. + +showSql:: + Specify whether Hibernate should show all SQL commands in the console (false by default). This is very verbose! + +formatSql:: + Specify whether Hibernate should format SQL commands (true by default) + +globalStatsInterval:: + Will log global statistics from Hibernate about executed DB queries and other things. + Statistics are always reported to server log at specified interval (in seconds) and are cleared after each report. + +schema:: + Specify the database schema to use + +NOTE: All these configuration switches and more are described in the link:{{book.jpa.link}}[the Hibernate chapter] + of {{book.jpa.name}}. + diff --git a/topics/database/jdbc.adoc b/topics/database/jdbc.adoc new file mode 100755 index 0000000000..4f28499d34 --- /dev/null +++ b/topics/database/jdbc.adoc @@ -0,0 +1,96 @@ +=== 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. +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. + +.Module Directory +image:../../{{book.images}}/db-module.png[] + +After you have done this, open up the _module.xml_ file and create the following XML + +.Module XML +[source,xml] +---- + + + + + + + + + + + + +---- + +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 +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 <>. 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: ++auth-server-standalone+ or +auth-server-clustered+ + +.Domain Profile +[source,xml] +---- + + ... + +---- + +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 +database. + +.JDBC Drivers +[source,xml] +---- + + + ... + + + org.h2.jdbcx.JdbcDataSource + + + + +---- + +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 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. + + +.Declare Your JDBC Drivers +[source,xml] +---- + + + ... + + + org.postgresql.Driver + + + org.h2.jdbcx.JdbcDataSource + + + + +---- diff --git a/topics/operating-mode.adoc b/topics/operating-mode.adoc index 9d27b3947b..bdd87b7f10 100755 --- a/topics/operating-mode.adoc +++ b/topics/operating-mode.adoc @@ -1,3 +1,5 @@ +[[_operating_mode]] + == Choosing an Operating Mode Before deploying {{book.project.name}} in a production environment you need to decide which type of operating mode