opendev/gerrit
Code Issues Proposed changes

Update auto-site initialization documentation

Browse Source 
I had trouble following the original wording, and after Id6e5348e there
were some inaccuracies. Rewrite the whole documentation to be more
streamlined, with only a single example.

Change-Id: Ib40e4bfa526583149494529f2673db9cd0780b73
This commit is contained in:
Dave Borowitz 2018-12-18 13:04:37 -08:00
parent a9064ca785
commit 7141c94f04
1 changed files with 22 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
Documentation/config-auto-site-initialization.txt
View File

@ -2,74 +2,41 @@
== Description
Gerrit supports automatic site initialization on server startup
when Gerrit runs in a servlet container. Both creation of a new site
and upgrade of an existing site are supported. By default, all packaged
plugins will be installed when Gerrit is deployed in a servlet container
and the location of the Gerrit distribution can be determined at
runtime. It is also possible to install only a subset of packaged
plugins or not install any plugins.
Gerrit supports automatic site initialization on server startup when Gerrit runs
in a servlet container. Both creation of a new site and upgrade of an existing
site are supported. By default, all packaged plugins will be installed when
Gerrit is deployed in a servlet container and the location of the Gerrit
distribution can be determined at runtime. It is also possible to install only a
subset of packaged plugins or not install any plugins.
This feature may be useful for such setups where Gerrit administrators
don't have direct access to the database and the file system of the
server where Gerrit should be deployed and, therefore, cannot perform
the init from their local machine prior to deploying Gerrit on such a
server. It may also make deployment and testing in a local servlet
container faster to set up as the init step could be skipped.
This feature may be useful for such setups where Gerrit administrators don't
have direct access to the file system of the server where Gerrit should be
deployed and, therefore, cannot perform the init from their local machine prior
to deploying Gerrit on such a server. It may also make deployment and testing in
a local servlet container faster to set up as the init step could be skipped.
== Gerrit Configuration
The site initialization will be performed only if the `gerrit.init`
system property exists. The value of the property is not used; only the
existence of the property matters.
In order to perform site initialization, define `gerrit.site_path` with the path
to your site. If the site already exists, this is the only required property.
If your site does not yet exist, set the `gerrit.init` system property to
automatically initialize the site.
If the `gerrit.site_path` system property is defined then the init is
run for that site. The database connectivity, in that case, is defined
in the `etc/gerrit.config`.
During initialization, if the `gerrit.install_plugins` property is not defined,
then all packaged plugins will be installed. If it is defined, then it is parsed
as a comma-separated list of plugin names to install. If the value is an empty
string then no plugins will be installed.
`gerrit.site_path` system property must be defined to run the init for
that site.
=== Example
[WARNING]
Defining the `jdbc/ReviewDb` JNDI property for an H2 database under the
path defined by `gerrit.site_path` will cause an incomplete auto
initialization and Gerrit will fail to start.
Opening a connection to such a database will create a subfolder under the
site path folder (in order to create the H2 database) and Gerrit will
no longer consider that site path to be new and, because of that,
skip some required initialization steps (for example, Lucene index
creation). In order to auto initialize Gerrit with an embedded H2
database use the `gerrit.site_path` to define the location of the review
site and don't define a JNDI resource with a URL under that path.
If the `gerrit.install_plugins` property is not defined then all packaged
plugins will be installed. If it is defined then it is parsed as a
comma-separated list of plugin names to install. If the value is an
empty string then no plugin will be installed.
=== Example 1
Prepare Tomcat so that a site is initialized at a given path using
the H2 database (if the site doesn't exist yet) or using whatever
database is defined in `etc/gerrit.config` of that site:
Prepare Tomcat so that a site is initialized at a given path (if the site
doesn't exist yet), installing all packaged plugins.
----
$ export CATALINA_OPTS='-Dgerrit.init -Dgerrit.site_path=/path/to/site'
$ catalina.sh start
----
=== Example 2
Assuming the database schema doesn't exist in the database defined
via the `jdbc/ReviewDb` JNDI property, initialize a new site using that
database and a given path:
----
$ export CATALINA_OPTS='-Dgerrit.init -Dgerrit.init_path=/path/to/site'
$ catalina.sh start
----
GERRIT
------
Part of link:index.html[Gerrit Code Review]