Here's some reference information on Gerrit's scalability and hardware requirements, file/directory structure, database, ports and connectivity.
Scalability and hardware requirements
- For estimated requirements and availability assumptions, see http://gerrit-documentation.googlecode.com/svn/Documentation/2.1.7/dev-design.html#_scalability.
- For hardware considerations, see http://code.google.com/p/gerrit/wiki/Scaling.
- For a detailed description of performance-related settings, see http://gerrit-documentation.googlecode.com/svn/Documentation/2.1.7/config-gerrit.html.
Gerrit directory structureGerrit expects a standardized directory structure under the GERRIT_SITE directory: /opt/collabnet/gerrit, the gerrit user's home directory. The /etc/default/gerritcodereview file contains the GERRIT_SITE variable and points to /opt/collabnet/gerrit.
Sub-directories of GERRIT_SITE (/opt/collabnet/gerrit):
- .ssh: contains the SSH key for the gerrit user; generated during installation and needs to be backed up.
- bin: binaries, startup script
- gerrit.war: the main Gerrit service
- gerrit-sync.jar: the Gerrit-TeamForge synchronization service
- gerrit.sh: SYSV-style init script; launches and shuts down; linked to /etc/init.d/gerrit
- cache: disk cache; does not need to be backed up; can always be re-generated on the fly; should be deleted after an upgrade or restore.
- etc: contains all configuration information; needs to be backed up.
- gerrit.config: the Gerrit configuration
- secure.config: obfuscated passwords and secrets
- log4j.properties: logging settings in log4j format
- gerritforge.mappings: defines how TeamForge access permissions are mapped to Gerrit access rights
- lib: libraries, potentially customer-specific extensions, treat like the bin directory
- logs: Gerrit log files; default configuration rotates logs daily, gzips old logs; debug files are rotated after they reach 10 MB; we keep 10 copies. You can make changes in Gerrit’s log4j.properties file at /opt/collabnet/gerrit/etc.
- audit.log: audit events
- system.log: INFO-level logging
- sshd.log: logs connections to Gerrit's SSH port (not system shell SSH)
- *.gc.log: information on garbage collector usage
Note: In co-hosted mode, TeamForge log rotation behavior will be used as default.
- /gitroot: default location for Git repositories. The default location can be changed using the setting in gerrit.config or by symlinking the directory. You need to back up this directory.
DatabaseGerrit stores runtime information about users, groups, code reviews and commits in a PostgreSQL database called reviewdb by default. You need to back up this database. If the Git integration is installed on the TeamForge server, it will use the same PostgreSQL install as TeamForge. If the integration is on a separate server, it will use a local PostgreSQL installation on that server. During installation, a new gerrit role and reviewdb schema get created. Note that Git does not, at any point, access TeamForge schema within the Postgres database.
host reviewdb gerrit samehost md5
host all all 127.0.0.1/32 identIf it exists, you need to comment it out (using #) to avoid clashing with this line inserted by installer:
host reviewdb gerrit samehost md5
Ports and connectivityGerrit opens three (TCP) ports: 9080, 9081 and 29418. You should expose only port 29418 outside localhost.
- 9080: the Gerrit Web interface
- This port will be proxied by Apache conf (prefix /gerrit) and doesn't need to be externally accessible. Do not expose this port to the outside.
- 9081: Gerrit-sync web service (REST)
In the Local (or co-hosted mode), TeamForge talks to the Gerrit REST API over localhost. Gerrit talks to TeamForge over its default SOAP URL.
The Git integration needs bidirectional connectivity to the TeamForge host. In the Remote (or distributed) mode, TeamForge talks to the Gerrit REST API over an Apache proxy rule (SSL-enabled if Apache is SSL-enabled on the integration server where Gerrit is running). Gerrit talks to TeamForge over its default SOAP URL.Do not expose this port to the outside.
- 29418: Gerrit SSH access
- Developers use the SSH protocol to push and pull source code to and from Gerrit. This
port needs to be open to users. Note: Gerrit ships its own SSH implementation and offers no shell access over this port.
Gerrit's integration with Continuous Integration (CI)
Backward compatibility notes on gerritforge.mappings
If you are a current user and do not want the code review policy feature introduced in the TeamForge Git integration version 7.0.0, you can continue to use your gerritforge.mappings file without any behavioral changes. To determine whether you are still using the old gerritforge.mapping file format, there is a new property called mapping_format_version. Its default value (if not mentioned) is 1. In the new template file, it is set to 2. This allows for future changes to the format. If the number cannot be parsed, we issue an error message and assume 2.
The following two paragraphs are very technical - they may not interest you if you want to upgrade, unless you've made extensive manual changes to access rights directly in the Gerrit web interface or use the programmatic access right infrastructure.
In the backward compatibility mode (mapping_format_versioncodeph> < 2), the only managed categories are READ, pHD, pTag, and OWN. Access rights of other categories (such as submit, review, forge identity) are be touched by GerritSynch. In mapping_format_versioncodeph> == 2, we support all categories in Gerrit 2.1.8 and if [<name of Git Repo Category>.]keep_rights_added_in_gerrit is set to false (which is the case for the default category, mandatory review and optional review), we wipe out access rights of previously unmanaged categories as well.
If a Gerrit access right category code is mentioned for a repository category, all previously existing access rights of that access right category are replaced as long as [<name of Git Repo Category>.]keep_rights_added_in_gerrit is set to false. If this property is set to true, and the backward compatibility mode is turned on, we only keep the existing access rights if they do not refer to refs/* or refs/tags/*. If this property is set to true and mapping_format_versioncodeph> is set to 2, we keep the existing access rights no matter what they refer to.
MappingObjects and Relationships are mapped from TeamForge to Gerrit, not the other way. The mapping rules are defined in /opt/collabnet/gerrit/etc/gerritforge.mappings.
|TeamForge Object||Gerrit Object|
|SCM repository in TeamForge project (containing project roles with SCM permissions)||Project|
|Project Role with SCM permission||Access right|
|TeamForge Relationship||Gerrit Relationship|
|SCM repository in TeamForge project with project roles with SCM permissions||SCM repository in TeamForge project with project roles with SCM permissions|
|User is part of a User Group that is assigned a Project Role||User is part of a Group (which corresponds to a TeamForge Project Role)|
|User is part of a User Group||User is part of a Group (which corresponds to a TeamForge User Group|
|Project Role is assigned SCM Admin permission (such as Admin, Delete and View, View and Commit, View Only, None)||Corresponding group is assigned Gerrit access rights matching the assigned TeamForge SCM permissions. The access rights are determined by the code review policy of the corresponding TeamForge repository|
|Gerrit Category Code||Gerrit Access Rights Category|