Added additional information on the install instructions. The installation instructions presumes much prior knowledge. This is an attempt at making some of that knowledge less implicit. Change-Id: I56195eedbe8c73248e2545a95f2237d16a1d54ed
diff --git a/Documentation/install.txt b/Documentation/install.txt index 6d477bb..6237fd7 100644 --- a/Documentation/install.txt +++ b/Documentation/install.txt
@@ -1,8 +1,17 @@ Gerrit Code Review - Installation Guide ======================================= -You need a SQL database to house the review metadata. Currently H2, -MySQL and PostgreSQL are the only supported databases. +[[requirements]] +Requirements +----------- +To run the Gerrit service, the following requirements must be met on +the host: + +* JDK, minimum version 1.6 http://www.oracle.com/technetwork/java/javase/downloads/index.html[Download] + +You'll also need a SQL database to house the review metadata. You have the +choice of either using the embedded H2 or to host your own MySQL or PostgreSQL. + [[download]] Download Gerrit @@ -20,6 +29,7 @@ If you would prefer to build Gerrit directly from source, review the notes under link:dev-readme.html[developer setup]. + [[createdb]] Database Setup -------------- @@ -28,15 +38,25 @@ H2 ~~ -During init Gerrit will automatically configure the embedded H2 -database. No additional configuration is necessary. Using the -embedded H2 database is the easiest way to get a Gerrit site up -and running. +During the init phase of Gerrit you will need to specify which database to use. +If you choose H2, Gerrit will automatically set up the embedded H2 database as +backend so no set up in advance is necessary. Also, no additional configuration is +necessary. Using the embedded H2 database is the easiest way to get a Gerrit +site up and running, making it ideal for proof of concepts or small team +servers. On the flip side, H2 is not the recommended option for large +corporate installations. This is because there is no easy way to interact +with the database while Gerrit is offline, it's not easy to backup the data, +and it's not possible to set up H2 in a load balanced/hotswap configuration. + [[createdb_postgres]] PostgreSQL ~~~~~~~~~~ +This option is more complicated than the H2 option but is recommended +for larger installations. It's the database backend with the largest userbase +in the Gerrit community. + Create a user for the web application within Postgres, assign it a password, create a database to store the metadata, and grant the user full rights on the newly created database: @@ -46,10 +66,14 @@ createdb -E UTF-8 -O gerrit2 reviewdb ---- + [[createdb_mysql]] MySQL ~~~~~ +This option is also more complicated than the H2 option. Just as with +PostgreSQL it's also recommended for larger installations. + Create a user for the web application within the database, assign it a password, create a database, and give the newly created user full rights on it: @@ -74,6 +98,11 @@ to as `'$site_path'`. If the embedded H2 database is being used, its data files will also be stored under this directory. +You also have to decide where to store your server side git repositories. This +can either be a relative path under `'$site_path'` or an absolute path +anywhere on your server system. You have to choose a place before commencing +your init phase. + Initialize a new site directory by running the init command, passing the path of the site directory to be created as an argument to the '-d' option. Its recommended that Gerrit Code Review be given its @@ -82,23 +111,27 @@ ---- sudo adduser gerrit2 sudo su gerrit2 - cd ~gerrit2 - java -jar gerrit.war init -d review_site + java -jar gerrit.war init -d /path/to/your/gerrit_application_directory ---- -If run from an interactive terminal, 'init' will prompt through a +'Please note:' If you choose a location where your new user doesn't +have any privileges, you may have to manually create the directory first and +then give ownership of that location to the `'gerrit2'` user. + +If run from an interactive terminal, the init command will prompt through a series of configuration questions, including gathering information -about the database created above. If the terminal is not interactive -init will make some reasonable default selections, and will use the -embedded H2 database. +about the database created above. If the terminal is not interactive, +running the init command will choose some reasonable default selections, +and will use the embedded H2 database. Once the init phase is complete, +you can review your settings in the file `'$site_path/etc/gerrit.config'`. -Init may need to download additional JARs to support optional selected -functionality. If a download fails a URL will be displayed and init -will wait for the user to manually download the JAR and store it in -the target location. +When running the init command, additional JARs might be downloaded to +support optional selected functionality. If a download fails a URL will +be displayed and init will wait for the user to manually download the JAR +and store it in the target location. -When 'init' is complete, the daemon will be automatically started +When the init phase is complete, the daemon will be automatically started in the background and your web browser will open to the site: ---- @@ -116,6 +149,14 @@ users will be automatically registered as unprivileged users. +Installation Complete +--------------------- + +Your base Gerrit server is now installed and running. You're now ready to +either set up more projects or start working with the projects you've already +imported. + + [[project_setup]] Project Setup -------------