| Deploying Gerrit's Manager Backend |
| ================================== |
| |
| The manager backend is a Java process that performs batch operations |
| on local Git repositories, based on the metadata recorded into the |
| Gerrit instance running on Google App Engine. |
| |
| To deploy the backend: |
| |
| ---- |
| $ make release-mgr |
| $ scp -r release/mgr you@some.server:mgr |
| --- |
| |
| |
| Running |
| ------- |
| |
| To start the backend server process: |
| |
| ---- |
| $ ./bin/mgr mgr.config & |
| ---- |
| |
| where mgr.config is the backend's configuration file (see below |
| for details on its format and options). |
| |
| To stop the backend, send it a SIGINT: |
| |
| ---- |
| kill -INT $mgrpid |
| ---- |
| |
| |
| Creating Gerrit Projects and Branches |
| ------------------------------------- |
| |
| To create new projects/branches in Gerrit to match those available |
| locally in Git run the mgr in the foreground with its sync option: |
| |
| ---- |
| $ ./bin/mgr mgr.config sync |
| ---- |
| |
| The sync subcommand will create a new Gerrit project for any new |
| Git repository found under codereview.basedir. It also creates |
| a new branch in Gerrit for any branch in any new or existing Git |
| repository. |
| |
| |
| |
| Manager Configuration |
| --------------------- |
| |
| The manager backend requires a configuration file to designate |
| which Git repositories it will have access to, and which Gerrit |
| instance it communicates with. |
| |
| The configuration file is in `git config` format and can thus be |
| automatically read/updated via `git config --file=<name>`. It can |
| also be hand-modified. For more details on the file format, see |
| `man git-config`. |
| |
| ---- |
| $ cat mgr.config |
| [user] |
| name = Gerrit Code Review |
| email = gerrit@localhost |
| |
| [codereview] |
| server = http://androidreview.appspot.com/ |
| basedir = /pub/scm/git |
| username = role-account@gmail.com |
| secureconfig = .secure-mgr-config |
| sleep = 60 |
| |
| [log] |
| file = mgr.log |
| level = debug |
| ---- |
| |
| A description of the major options follows: |
| |
| user.name:: |
| Author/committer name Gerrit records when creating an |
| automatic merge commit. |
| |
| user.email:: |
| Author/committer email Gerrit records when creating an |
| automatic merge commit. |
| |
| codereview.server:: |
| URL of the Gerrit Google App Engine instance providing |
| database support and web user interface to the code review |
| system. Presently only HTTP is supported. Future releases |
| of Gerrit may support HTTPS, if/when Google App Engine ever |
| supports HTTPS. |
| |
| codereview.basedir:: |
| Root directory that all Git repositories are relative to. |
| Repositories in this directory should be bare repositories. |
| The name of a project in Gerrit is appended to this directory |
| to determine the path of the corresponding Git repository |
| where change branches are stored and merges take place. |
| |
| codereview.username:: |
| (Optional) Google Account username to authenticate to |
| codereview.server with. This option is only required if the |
| Gerrit instance has been set to ADMIN_ONLY=1. (Normally the |
| manager backend uses a more secure authentication strategy.) |
| If set, make sure codereview.password is also in the secure |
| configuration file. |
| |
| codereview.secureconfig:: |
| Path to the secure configuration file (see below). |
| A relative path is evaluated relative to the main |
| configuration file. |
| |
| codereview.sleep:: |
| Number of seconds between queries when Gerrit says there |
| is nothing waiting to be processed. This is the maximum |
| latency between when an upload or merge request is first |
| stored in the data store and when the backend can process it. |
| |
| codereview.memory:: |
| Maximum amount of Java heap memory to give to the manager |
| process. Valid values are in bytes, with standard "m" and |
| "g" suffixes for "megabytes" and "gigabytes". E.g. "256m" |
| would assign up to 256 megabytes of memory to the manager. |
| |
| log.file:: |
| Path to the log file the server writes messages to. If not |
| set messages are sent to stdout. |
| |
| log.level:: |
| Set the verbosity of the logging. Supported values are: |
| fatal, error, warning, info, debug, trace. Later levels |
| include all messages from all earlier levels. |
| |
| |
| Secure Configuration File |
| ------------------------- |
| |
| The secure configuration file stores additional details which |
| should never be made public. This file should be protected with |
| filesystem level access controls, e.g. "chmod 0600" on UNIX prior |
| to writing any information into it. |
| |
| ---- |
| $ cat .secure-mgr-config |
| [codereview] |
| password = g3rr1t1sc001 |
| internalapikey = somebiglongkeystring |
| ---- |
| |
| codereview.password:: |
| (Optional) Password matching the Google Account listed |
| in codereview.username in the main configuration file. |
| This value is only required if the Gerrit instance is in |
| ADMIN_ONLY=1 mode and thus needs the backend to authenticate |
| with a Google Account. |
| |
| codereview.internalapikey:: |
| The private key used for HMAC authentication between the |
| manager backend and the Gerrit instance running on Google |
| App Engine. Any application developer/administrator can |
| get this key from http://APPID.appspot.com/admin/settings |
| |
| |
| Parallel Operation Concerns |
| --------------------------- |
| |
| The backend uses aggressive caching, and is not yet fully safe to |
| run concurrently with command line Git operations such as `git gc`, |
| `git repack` or `git pack-refs`. |
| |
| Until the backend has been fully patched to support concurrent |
| operations, do not run Git operations in repositories under |
| codereview.basedir while a backend is running on that directory. |
| |
| In order to repack safely, stop the backend, run the repack activity, |
| then start it back up again. |