From 9ad8ba528e4faa1360fedad3a53fb9c233f40e43 Mon Sep 17 00:00:00 2001 From: "Shawn O. Pearce" Date: Fri, 11 Dec 2009 19:06:21 -0800 Subject: [PATCH] documentation: Rewrite installation guide to use new init process Now that installation is more or less just one command with a guided interaction asking configuration questions we can start to simplify the user guide. Change-Id: Id98f9843d29e1fe0b445c2a714ace9ec3938ff79 Signed-off-by: Shawn O. Pearce --- Documentation/config-apache2.txt | 77 +++++ Documentation/install-j2ee.txt | 116 ++++++++ Documentation/install.txt | 471 ++++++++----------------------- 3 files changed, 316 insertions(+), 348 deletions(-) create mode 100644 Documentation/config-apache2.txt create mode 100644 Documentation/install-j2ee.txt diff --git a/Documentation/config-apache2.txt b/Documentation/config-apache2.txt new file mode 100644 index 0000000000..67c82ca0d7 --- /dev/null +++ b/Documentation/config-apache2.txt @@ -0,0 +1,77 @@ +Gerrit Code Review - Apache 2 Reverse Proxy +=========================================== + +Description +----------- + +Gerrit can be configured to run behind an Apache server using +'mod_proxy'. This allows Apache to bind to the privileged ports 80 +(or 443 for SSL), as well as offloads the SSL processing overhead +from Java to optimized native C code. + + +Configuration +------------ + +Enable the necessary Apache2 modules: + +---- + a2enmod proxy_http + a2enmod ssl ; # optional, needed for HTTPS / SSL +---- + +Ensure `'$site_path'/etc/gerrit.config` has the property +link:config-gerrit.html#httpd.listenUrl[httpd.listenUrl] configured +to use 'proxy-http://' or 'proxy-https://' and a free port number. +This may have already been configured if proxy support was enabled +during 'init'. + +---- + [httpd] + listenUrl = proxy-http://127.0.0.1:8081/r/ +---- + +Configure an Apache VirtualHost to proxy to the Gerrit daemon, setting +the 'ProxyPass' line to use the 'http://' URL configured above. + +---- + + ServerName review.example.com + + ProxyRequests Off + ProxyVia Off + ProxyPreserveHost On + + + Order deny,allow + Allow from all + + + ProxyPass /r/ http://127.0.0.1:8081/r/ + +---- + +SSL +~~~ + +To enable Apache to perform the SSL processing, use 'proxy-https://' +in httpd.listenUrl within Gerrit's configuration file, and enable +the SSL engine in the Apache VirtualHost block: + +---- + + SSLEngine on + SSLCertificateFile conf/server.crt + SSLCertificateKeyFile conf/server.key + + ... same as above ... + +---- + +See the Apache 'mod_ssl' documentation for more details on how to +configure SSL within the server, like controlling how strong of an +encryption algorithm is required. + +GERRIT +------ +Part of link:index.html[Gerrit Code Review] diff --git a/Documentation/install-j2ee.txt b/Documentation/install-j2ee.txt new file mode 100644 index 0000000000..3233b4d47e --- /dev/null +++ b/Documentation/install-j2ee.txt @@ -0,0 +1,116 @@ +Gerrit Code Review - J2EE Installation +====================================== + +Description +----------- + +Gerrit binary distributions include a standalone Jetty servlet +container, but are packaged as a standard WAR file to permit easy +deployment to other existing container installations if using the +standalone daemon is not desired. + +Gerrit Code Review can be installed into any J2EE servlet container, +including popular open source containers such as Jetty or Tomcat, or +any commerical server which supports the J2EE servlet specification. + + +Installation +------------ + +* Complete the link:install.html#createdb[database setup] and + link:install.html#init[site initialization] tasks described + in the standard installation documentation. + +* Stop the embedded deamon that was automatically started by 'init': ++ +---- + review_site/bin/gerrit.sh stop +---- + +* Deploy the 'gerrit.war' file to your application server. ++ +The deployment process differs between servers, but typically this +can be accomplished by copying 'gerrit.war' into the 'webapps/' +subdirectory of the container's installation. + +* Configure JNDI DataSource 'jdbc/ReviewDb'. ++ +This DataSource must point to the database you created above. +Don't forget to ensure your JNDI configuration can load the +necessary JDBC drivers. You may wish to ensure connection pooling +is configured and enabled within the DataSource. + +* ('Optional') Install Bouncy Castle Crypto API ++ +If you enabled Bouncy Castle Crypto during 'init', copy the JAR +from `'$site_path'/lib` into your servlet container's extensions +directory so its available to Gerrit Code Review. + + +Jetty 7.x +--------- +These directions will configure Gerrit as the default web +application, allowing URLs like `http://example.com/4543` to jump +directly to change 4543. + +Download and unzip a release version of Jetty. From here on we +call the unpacked directory `$JETTY_HOME`. + +* link:http://www.eclipse.org/jetty/downloads.php[Jetty Downloads] + +If this is a fresh installation of Jetty, move into the installation +directory and do some cleanup to remove the sample webapps: +---- + cd $JETTY_HOME + rm -rf contexts/* webapps/* +---- + +Copy Gerrit Code Review into the deployment: +---- + cp ~/gerrit.war webapps/gerrit.war + java -jar webapps/gerrit.war cat extra/jetty7/gerrit.xml >contexts/gerrit.xml +---- + +Install the required additional libraries by copying them into the +`'$JETTY_HOME'/lib/ext` directory: + +---- + cp ../review_db/lib/* lib/ext/ + java -jar webapps/gerrit.war cat lib/commons-dbcp-1.2.2.jar >lib/ext/commons-dbcp-1.2.2.jar + java -jar webapps/gerrit.war cat lib/commons-pool-1.5.3.jar >lib/ext/commons-pool-1.5.3.jar + java -jar webapps/gerrit.war cat lib/h2-1.2.122.jar >lib/ext/h2-1.2.122.jar + java -jar webapps/gerrit.war cat lib/postgresql-8.4-701.jdbc4.jar >lib/ext/postgresql-8.4-701.jdbc4.jar +---- + +Edit `'$JETTY_HOME'/contexts/gerrit.xml` to correctly configure +the database and outgoing SMTP connections, especially the user +and password fields. + +If OpenID authentication (or certain enterprise single-sign-on +solutions) is being used, you may need to increase the +header buffer size parameter, due to very long header lines +being used by the OpenID authentication handshake process. +Add the following to `'$JETTY_HOME'/etc/jetty.xml` under +`org.eclipse.jetty.server.nio.SelectChannelConnector`: + +---- + 16384 +---- + +To start automatically when the system boots, create a start +script and modify it for your configuration: + +---- + java -jar webapps/gerrit.war --cat extra/jetty7/gerrit-jetty.sh >/etc/init.d/gerrit-jetty.sh + vi /etc/init.d/gerrit-jetty.sh +---- + +[TIP] +Under Jetty, restarting the web application (e.g. after modifying +`system_config`) is as simple as touching the context config file: +`'$JETTY_HOME'/contexts/gerrit.xml` + + +GERRIT +------ +Part of link:index.html[Gerrit Code Review] diff --git a/Documentation/install.txt b/Documentation/install.txt index 19472eb868..c3da82827a 100644 --- a/Documentation/install.txt +++ b/Documentation/install.txt @@ -1,32 +1,13 @@ Gerrit Code Review - Installation Guide ======================================= -You need a SQL database to house the Gerrit2 metadata. Currently -H2, MySQL and PostgreSQL are the only supported databases. +You need a SQL database to house the review metadata. Currently H2, +MySQL and PostgreSQL are the only supported databases. -Important Links +[[download]] +Download Gerrit --------------- -PostgreSQL: - -* http://www.postgresql.org/docs/[Documentation] -* link:http://jdbc.postgresql.org/download.html[JDBC Driver] - -MySQL: - -* http://dev.mysql.com/doc/[Documentation] -* http://dev.mysql.com/downloads/connector/j/5.0.html[JDBC Driver] - -Optional Libraries: - -* link:http://commons.apache.org/pool/download_pool.cgi[Commons Pool] -* link:http://commons.apache.org/dbcp/download_dbcp.cgi[Commons DBCP] -* link:http://www.bouncycastle.org/java.html[Bouncy Castle Crypto API] - - -Downloading Gerrit ------------------- - Current and past binary releases of Gerrit can be obtained from the downloads page at the project site: @@ -36,172 +17,146 @@ Download any current `*.war` package. The war will be referred to as `gerrit.war` from this point forward, so you may find it easier to rename the downloaded file. +If you would prefer to build Gerrit directly from source, review +the notes under link:dev-readme.html[developer setup]. -Building Gerrit From Source ---------------------------- +[[createdb]] +Database Setup +-------------- -Alternatively, you can build the application distribution using -Maven from a source download obtained directly from Git: +[[createdb_h2]] +H2 +~~ -==== - git clone git://android.git.kernel.org/tools/gerrit.git - cd gerrit - mvn clean package - cp gerrit-war/target/gerrit-*.war ...YOUR.DEST.../gerrit.war -==== - -The first build may take a while as dependencies are searched -for and downloaded from Maven distribution repositories. - -Apache Maven: - -* http://maven.apache.org/download.html[Download] -* http://maven.apache.org/run-maven/index.html[Running Maven] - - -Setting up the Database ------------------------ +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. +[[createdb_postgres]] PostgreSQL ~~~~~~~~~~ -Create a Gerrit specific user as a normal user (no superuser access) -and assign it an encrypted password: +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: -==== +---- createuser -A -D -P -E gerrit2 -==== - -Create the database to store the Gerrit metadata, and set the user -you just created as the owner of that database: - -==== createdb -E UTF-8 -O gerrit2 reviewdb -==== +---- +[[createdb_mysql]] MySQL ~~~~~ -Create a Gerrit specific user within the database and assign it a -password, create a database, and give the user full rights: +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: + +---- + mysql -==== CREATE USER 'gerrit2'@'localhost' IDENTIFIED BY 'secret'; CREATE DATABASE reviewdb; ALTER DATABASE reviewdb charset=latin1; GRANT ALL ON reviewdb.* TO 'gerrit2'@'localhost'; FLUSH PRIVILEGES; -==== +---- -Initialize the Schema ---------------------- +[[init]] +Initialize the Site +------------------- -Create the Gerrit 2 Tables -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Gerrit stores configuration files, the server's SSH keys, and the +managed Git repositories under a local directory, typically referred +to as `'$site_path'`. If the embedded H2 database is being used, +its data files will also be stored under this directory. -Either run CreateSchema from the command line: +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 +own user account on the host system: + +---- + sudo adduser gerrit2 + sudo su gerrit2 + cd ~gerrit2 + + java -jar gerrit.war init -d review_site +---- + +If run from an interactive terminal, 'init' 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. + +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 'init' is complete, the daemon will be automatically started +in the background and your web browser will open to the site: + +---- + Initialized /home/gerrit2/review_site + Executing /home/gerrit2/review_site/bin/gerrit.sh start + Starting Gerrit Code Review: OK + Waiting for server to start ... OK + Opening browser ... +---- + +When the browser opens, sign in to Gerrit through the web interface. +The first user to sign-in and register an account will be +automatically placed into the fully privileged Administrators group, +permitting server management over the web and over SSH. Subsequent +users will be automatically registered as unprivileged users. + + +[[project_setup]] +Project Setup +------------- + +See link:project-setup.html[Project Setup] for further details on +how to register a new project with Gerrit. This step is necessary +if existing Git repositories were not imported during 'init'. + + +[[rc.d]] +Start/Stop Daemon +----------------- + +To control the Gerrit Code Review daemon that is running in the +background, use the rc.d style start script created by 'init': ==== - java -jar gerrit.war --cat extra/GerritServer.properties_example >GerritServer.properties - edit GerritServer.properties - - java -jar gerrit.war CreateSchema + review_site/bin/gerrit.sh start + review_site/bin/gerrit.sh stop + review_site/bin/gerrit.sh restart ==== -Or, run the application once in a container to force it to initialize -the database schema before accessing it. (See below for deployment -setup documentation.) If you use this approach, it is recommended -that you stop the application before continuing with the setup. - -Add Indexes -~~~~~~~~~~~ - -A script should be run to create the query indexes, so Gerrit -can avoid table scans when looking up information. Run the -index script through your database's query tool. - -PostgreSQL: +('Optional') Link the gerrit.sh script into rc3.d so the daemon +automatically starts and stops with the operating system: ==== - java -jar gerrit.war --cat sql/index_postgres.sql | psql reviewdb -U gerrit2 -W + sudo ln -snf `pwd`/review_site/bin/gerrit.sh /etc/init.d/gerrit.sh + sudo ln -snf ../init.d/gerrit.sh /etc/rc3.d/S90gerrit ==== -MySQL: +To install Gerrit into an existing servlet container instead of using +the embedded Jetty server, see +link:install-j2ee.html[J2EE installation]. -==== - java -jar gerrit.war --cat sql/index_generic.sql | mysql reviewdb -u gerrit2 -p - java -jar gerrit.war --cat sql/mysql_nextval.sql | mysql reviewdb -u gerrit2 -p -==== -Configure site_path -~~~~~~~~~~~~~~~~~~~ +[[customize]] +Site Customization +------------------ -This directory holds server-specific configuration files and -assets used to customize the deployment. Gerrit needs read -access (but not write access) to the directory. The path -is stored in `system_config.site_path`, so you will need to -update the database with this value. - -==== - mkdir /home/gerrit2/cfg - cd /home/gerrit2/cfg - - UPDATE system_config SET site_path='/home/gerrit2/cfg' -==== - -When '$site_path' is referenced below, it refers to the path set in the SQL above. - -SSH Host Keys -~~~~~~~~~~~~~ - -If you choose to install the Bouncy Castle Crypto APIs (see below) -you must create an RSA, DSA, or both, host keys for the daemon: - -==== - mkdir etc - ssh-keygen -t rsa -P '' -f etc/ssh_host_rsa_key - ssh-keygen -t dsa -P '' -f etc/ssh_host_dsa_key -==== - -These keys are used as the host keys for the internal SSH daemon -run by Gerrit. You may wish to backup these key files to ensure -they can be restored in the event of a disaster. - -The private key files (`ssh_host_rsa_key`, `ssh_host_dsa_key`) should -be readable *only* by the account that is executing Gerrit2's web -application container. It is a security risk to make these files -readable by anyone else. - -If you don't install Bouncy Castle, Gerrit will automatically create -a host key and save a copy to `'$site_path'/etc/ssh_host_key` -during first startup. For this to work correctly, Gerrit will -require write access to the directory. - -Create Git Repository Base -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This directory holds the Git repositories that Gerrit knows about -and can service. Gerrit needs write access to this directory and -any Git repository stored within it. - -==== - mkdir /srv/git - git config --file '$site_path'/etc/gerrit.config gerrit.basePath /srv/git -==== - -You may wish to consider also exporting this directory over the -anonymous git:// protocol, as it is more efficient than Gerrit's -internal ssh daemon. See the `git-daemon` documentation for details -on how to configure this if anonymous access is desired. - -* http://www.kernel.org/pub/software/scm/git/docs/git-daemon.html[man git-daemon] - -Futher Configuration -~~~~~~~~~~~~~~~~~~~~ - -Gerrit2 supports some site-specific customizations. These are -optional and are not required to run a server, but may be desired. +Gerrit Code Review supports some site-specific customization options. +For more information, see the related topic in this manual: * link:config-sso.html[Single Sign-On Systems] * link:config-replication.html[Git Replication/Mirroring] @@ -210,206 +165,26 @@ optional and are not required to run a server, but may be desired. * link:config-gerrit.html[Other System Settings] -Application Deployment ------------------------ +[[anonymous_access]] +Anonymous Access +---------------- -Jetty -~~~~~ +Exporting the Git repository directory +(link:config-gerrit.html#gerrit.basePath[gerrit.basePath]) over the +anonymous, unencrypted git:// protocol is more efficient than +Gerrit's internal SSH daemon. See the `git-daemon` documentation +for details on how to configure this if anonymous access is desired. -[NOTE] -The instructions listed here were tested with Jetty 6.1.14 or later. -These are known to not work on much older versions, such as 6.1.3. - -These directions will configure Gerrit as the default web -application, allowing URLs like `http://example.com/4543` to -jump directly to change 4543. - -Download and unzip a release version of Jetty. From here on we -call the unpacked directory `$JETTY_HOME`. - -* link:http://www.eclipse.org/jetty/downloads.php[Jetty Downloads] - -Install the required JDBC drivers by copying them into the -`'$JETTY_HOME'/lib/ext` directory. Drivers can be obtained from -their source projects: - -* link:http://jdbc.postgresql.org/download.html[PostgreSQL JDBC Driver] -* link:http://commons.apache.org/pool/download_pool.cgi[Commons Pool] -* link:http://commons.apache.org/dbcp/download_dbcp.cgi[Commons DBCP] - -Consider installing Bouncy Castle Cypto APIs into the -`'$JETTY_HOME'/lib/ext` directory. Some of the Bouncy Castle -implementations are faster than then ones that come in the JRE, -and they may support additional encryption algorithms: - -* link:http://www.bouncycastle.org/java.html[Bouncy Castle Crypto API] - -Copy Gerrit into the deployment: -==== - cd $JETTY_HOME - cp ~/gerrit.war webapps/gerrit.war - java -jar webapps/gerrit.war --cat extra/jetty7/gerrit.xml >contexts/gerrit.xml - rm -f contexts/test.xml -==== - -Edit `'$JETTY_HOME'/contexts/gerrit.xml` to correctly configure -the database and outgoing SMTP connections, especially the user -and password fields. - -If OpenID authentication (or certain enterprise single-sign-on -solutions) is being used, you may need to increase the -header buffer size parameter, due to very long header lines. -Add the following to `'$JETTY_HOME'/etc/jetty.xml` under -`org.eclipse.jetty.server.nio.SelectChannelConnector`: - -==== - 16384 -==== - -To start automatically when the system boots, create a start -script and modify it for your configuration: - -==== - java -jar gerrit.war --cat extra/jetty7/gerrit-jetty.sh >/etc/init.d/gerrit-jetty.sh - vi /etc/init.d/gerrit-jetty.sh -==== - -[TIP] -Under Jetty, restarting the web application (e.g. after modifying -`system_config`) is as simple as touching the context config file: -`'$JETTY_HOME'/contexts/gerrit.xml` - -Port 80 -^^^^^^^ - -To deploy on port 80, you should configure Jetty to listen on another -port, such as 127.0.0.1:8081 (like the start script above does) -and then follow the <> section below. - -Port 443 (HTTPS / SSL) -^^^^^^^^^^^^^^^^^^^^^^ - -To deploy on port 443 with SSL enabled, unpack the SSL proxy handling -rule into `'$JETTY_HOME'/etc`: -==== - cd $JETTY_HOME - java -jar webapps/gerrit.war --cat extra/jetty7/jetty_sslproxy.xml >etc/jetty_sslproxy.xml -==== - -Create a start script like the one above, configuring Jetty to -listen on another port, such as 127.0.0.1:8081. - -Set `gerrit.canonicalWebUrl` in `'$site_path'/etc/gerrit.config` -to an `https://` style URL for your application, so that non-SSL -connections are automatically upgraded to SSL by issuing a redirect. -Gerrit does not currently support a dual http/https usage on the -same site as it doesn't know when to upgrade a non-secure connection -to a secure one if data needs to be protected. - -Follow the <> section below to setup an -Apache2 server to handle SSL for Jetty. +* http://www.kernel.org/pub/software/scm/git/docs/git-daemon.html[man git-daemon] -[[other_containers]]Other Servlet Containers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +External Documentation Links +---------------------------- -Deploy the `gerrit-*.war` file to your application server as -`gerrit.war`. +* http://www.postgresql.org/docs/[PostgreSQL Documentation] +* http://dev.mysql.com/doc/[MySQL Documentation] +* http://www.kernel.org/pub/software/scm/git/docs/git-daemon.html[git-daemon] -Configure the JNDI DataSource `jdbc/ReviewDb` for the Gerrit web -application context to point to the database you just created. -Don't forget to ensure your JNDI configuration can load the -necessary JDBC drivers. - -('Optional') Add Bouncy Castle Crypto API to the web application's -classpath. Usually its best to load this library from the servlet -container's extensions directory, but gerrit.war could also be -manually repacked to include it. - -[[apache2]]Apache2 Reverse Proxy -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Enable the necessary Apache2 modules: - -==== - a2enmod proxy_http - a2enmod disk_cache ; # optional, but helps performance - - a2enmod ssl ; # optional, needed for HTTPS / SSL - a2enmod headers ; # optional, needed for HTTPS / SSL -==== - -then setup a VirtualHost to proxy to Gerrit's servlet container, -setting the `ProxyPass` line to use the port number you configured -in your servlet container's configuration: - -======================================= - - ServerName review.example.com - # - ProxyRequests Off - ProxyVia Off - ProxyPreserveHost On - # - - Order deny,allow - Allow from all - - ProxyPass / http://127.0.0.1:8081/ - # - - CacheEnable disk / - CacheIgnoreHeaders Set-Cookie - - -======================================= - -if you are using SSL with a Jetty container: - -==== - - ServerName review.example.com - # - SSLEngine on - SSLCertificateFile conf/server.crt - SSLCertificateKeyFile conf/server.key - # - ProxyRequests Off - ProxyVia Off - ProxyPreserveHost On - ProxyPass / http://127.0.0.1:8081/ - RequestHeader set X-Forwarded-Scheme https - # - - CacheEnable disk / - CacheIgnoreHeaders Set-Cookie - - -==== - -See the Apache `mod_ssl` documentation for more details on how to -configure SSL within the server, like controlling how strong of an -encryption algorithm is required. - -For Gerrit, the only difference between plain HTTP and HTTPS is -adding the "`RequestHeader set X-Forwarded-Scheme https`" line -within the SSL enabled virtual host. - - -Administrator Setup -------------------- - -Sign in to Gerrit through the web interface. The first user -to register or sign-in will be automatically placed into the -Administrators group. All subsequent users will be treated as -unprivileged users. - - -Project Setup -------------- - -See link:project-setup.html[Project Setup] for further details on -how to register a project with Gerrit. GERRIT ------