Tri's external memory

Gerrit - Session 1 Installation & Initial Architecture

3 min read

Goal

Set up a personal Gerrit server to practice:

  • Jujutsu (jj)
  • Gerrit code review
  • Stacked reviews
  • Git internals

The objective is not merely to have a working server, but to understand
why Gerrit is designed the way it is.

Final Architecture

Internet
      │
HTTPS (443)
      │
Nginx
      │
127.0.0.1:8080
      │
   Gerrit
      │
 ├── H2 Database
 ├── Lucene Index
 ├── Git Repositories
 └── SSH (29418)

SSH is exposed directly on port 29418.

HTTP is reachable only through Nginx.

Installation Summary

Operating System

  • Ubuntu 24.04 LTS
  • Java 21
  • Git 2.43

Gerrit Version

3.14.1

Configuration Choices

Git Repository Location

Default:

/site/git

Why?

Keeps the whole Gerrit installation self-contained.

Database

Selected:

H2

Why?

  • Embedded
  • No PostgreSQL setup
  • Appropriate for a personal lab
  • Easy backup

Search Index

Selected:

Lucene

Why?

  • Built into Gerrit
  • No Elasticsearch/OpenSearch
  • Suitable for small installations

Authentication

Selected:

DEVELOPMENT_BECOME_ANY_ACCOUNT

Why?

Allows quickly becoming any account during experiments.

Excellent for learning.

Not suitable for production.

Signed Push

Selected:

Disabled

Why?

Signed Push authenticates the push operation, not commits.

Rarely used.

Can be explored later.

Verified Label

Selected:

Installed

Why?

Separates:

  • Human review (Code-Review)
  • CI result (Verified)

This resembles a real corporate Gerrit workflow.

SMTP

Selected:

none

Why?

The server currently has no outbound mail server.

Email notifications can be configured later.

Reverse Proxy

Selected:

Yes

Why?

Nginx terminates HTTPS.

Gerrit only listens locally.

HTTP

Selected:

127.0.0.1:8080

Why?

Users should never access Gerrit directly.

All traffic passes through Nginx.

SSH

Final configuration:

*:29418

Why?

Allows Git/jj clients to push over SSH.

Canonical URL

Selected:

https://gerrit.domain.com

Why?

Stable URL for browser access and future email links.

Internal Repositories

Immediately after installation Gerrit created:

  • All-Projects.git
  • All-Users.git

These are not ordinary projects.

They contain Gerrit’s own configuration and account data.

This is one of Gerrit’s defining design principles:

Store configuration in Git whenever possible.

Problems Encountered

Administrator creation failed

Cause:

The SSH public key path was incorrect.

Resolution:

Re-ran initialization and skipped importing the SSH key.

SSH listen address

Initially configured as:

127.0.0.1:29418

Corrected to:

*:29418

Reason:

Remote Git/jj clients must reach Gerrit’s SSH service.

HTTPS

After Gerrit was reachable locally:

  1. Added Nginx reverse proxy.
  2. Issued TLS certificate with Certbot.
  3. Verified access at:
https://gerrit.domain.com

Key Takeaways

  • Gerrit uses Git internally for much more than source code.
  • HTTP should stay behind Nginx.
  • SSH is the primary protocol for Git/jj interaction.
  • H2 + Lucene is an excellent learning setup.
  • Development authentication is ideal for experimentation.

Next Session

  1. Explore All-Projects.git
  2. Explore All-Users.git
  3. Understand Gerrit permissions
  4. Create the first project
  5. Upload SSH key
  6. Push with Git
  7. Push with Jujutsu
  8. Explore Change-Id
  9. Explore refs/changes/*
  10. Practice stacked reviews

Graph View

Backlinks