GitLab Documentation

GitLab Geo database replication

This document describes the minimal steps you have to take in order to replicate your GitLab database into another server. You may have to change some values according to your database setup, how big it is, etc.

Table of Contents

PostgreSQL replication

The GitLab primary node where the write operations happen will connect to primary database server, and the secondary ones which are read-only will connect to secondary database servers (which are read-only too).

Note: In many databases documentation you will see primary being references as master and secondary as either slave or standby server (read-only).

Prerequisites

The following guide assumes that:

Step 1. Configure the primary server

For Omnibus installations

  1. SSH into your GitLab primary server and login as root:

    sudo -i
    
  2. Omnibus GitLab has already a replication user called gitlab_replicator. You must set its password manually. Replace thepassword with a strong password:

    sudo -u gitlab-psql /opt/gitlab/embedded/bin/psql -h /var/opt/gitlab/postgresql \
         -d template1 \
         -c "ALTER USER gitlab_replicator WITH ENCRYPTED PASSWORD 'thepassword'"
    
  3. Edit /etc/gitlab/gitlab.rb and add the following:

    postgresql['listen_address'] = "1.2.3.4"
    postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/32','1.2.3.4/32']
    postgresql['md5_auth_cidr_addresses'] = ['5.6.7.8/32']
    postgresql['sql_replication_user'] = "gitlab_replicator"
    postgresql['wal_level'] = "hot_standby"
    postgresql['max_wal_senders'] = 10
    postgresql['wal_keep_segments'] = 10
    postgresql['hot_standby'] = "on"
    

    Where 1.2.3.4 is the public IP address of the primary server, and 5.6.7.8 the public IP address of the secondary one.

    For security reasons, PostgreSQL by default only listens on the local interface (e.g. 127.0.0.1). However, GitLab Geo needs to communicate between the primary and secondary nodes over a common network, such as a corporate LAN or the public Internet. For this reason, we need to configure PostgreSQL to listen on more interfaces.

    The listen_address option opens PostgreSQL up to external connections with the interface corresponding to the given IP. See the PostgreSQL documentation for more details.

    Note that if you are running GitLab Geo with a cloud provider (e.g. Amazon Web Services), the internal interface IP (as provided by ifconfig) may be different from the public IP address. For example, suppose you have a nodes with the following configuration:

    Node Type Internal IP External IP
    Primary 10.1.5.3 54.193.124.100
    Secondary 10.1.10.5 54.193.100.155

    In this case, for 1.2.3.4 use the internal IP of the primary node: 10.1.5.3. For 5.6.7.8, use the external of the secondary node: 54.193.100.155.

    If you want to add another secondary, the relevant setting would look like:

    postgresql['md5_auth_cidr_addresses'] = ['5.6.7.8/32','11.22.33.44/32']
    

    Edit the wal values as you see fit.

  4. Check to make sure your firewall rules are set so that the secondary nodes can access port 5432 on the primary node.

  5. Save the file and reconfigure GitLab for the changes to take effect.

  6. Now that the PostgreSQL server is set up to accept remote connections, run netstat -plnt to make sure that PostgreSQL is listening to the server's public IP.

  7. Continue to set up the secondary server.


For installations from source

  1. SSH into your database primary server and login as root:

    sudo -i
    
  2. Create a replication user named gitlab_replicator:

    sudo -u postgres psql -c "CREATE USER gitlab_replicator REPLICATION ENCRYPTED PASSWORD 'thepassword';"
    
  3. Edit postgresql.conf to configure the primary server for streaming replication (for Debian/Ubuntu that would be /etc/postgresql/9.x/main/postgresql.conf):

    listen_address = '1.2.3.4'
    wal_level = hot_standby
    max_wal_senders = 5
    checkpoint_segments = 10
    wal_keep_segments = 10
    hot_standby = on
    

    See the Omnibus notes above for more details of listen_address.

    Edit the wal values as you see fit.

  4. Set the access control on the primary to allow TCP connections using the server's public IP and set the connection from the secondary to require a password. Edit pg_hba.conf (for Debian/Ubuntu that would be /etc/postgresql/9.x/main/pg_hba.conf):

    host    all             all                      127.0.0.1/32    trust
    host    all             all                      1.2.3.4/32      trust
    host    replication     gitlab_replicator        5.6.7.8/32      md5
    

    Where 1.2.3.4 is the public IP address of the primary server, and 5.6.7.8 the public IP address of the secondary one. If you want to add another secondary, add one more row like the replication one and change the IP address:

      host    all             all                      127.0.0.1/32    trust
      host    all             all                      1.2.3.4/32      trust
      host    replication     gitlab_replicator        5.6.7.8/32      md5
      host    replication     gitlab_replicator        11.22.33.44/32  md5
    
  5. Restart PostgreSQL for the changes to take effect.

  6. Now that the PostgreSQL server is set up to accept remote connections, run netstat -plnt to make sure that PostgreSQL is listening to the server's public IP.

Step 2. Configure the secondary server

For Omnibus installations

  1. SSH into your GitLab secondary server and login as root:

    sudo -i
    
  2. Test that the remote connection to the primary server works:

     sudo -u gitlab-psql /opt/gitlab/embedded/bin/psql -h 1.2.3.4 -U gitlab_replicator -d gitlabhq_production -W
    

    When prompted enter the password you set in the first step for the gitlab_replicator user. If all worked correctly, you should see the database prompt.

  3. Exit the PostgreSQL console:

    \q
    
  4. Edit /etc/gitlab/gitlab.rb and add the following:

    postgresql['wal_level'] = "hot_standby"
    postgresql['max_wal_senders'] = 10
    postgresql['wal_keep_segments'] = 10
    postgresql['hot_standby'] = "on"
    gitlab_rails['auto_migrate'] = false # prevents migrations to be executed on the secondary server
    
  5. Reconfigure GitLab for the changes to take effect.

  6. Continue to initiate the replication process.


For installations from source

  1. SSH into your database secondary server and login as root:

    sudo -i
    
  2. Test that the remote connection to the primary server works:

    sudo -u postgres psql -h 1.2.3.4 -U gitlab_replicator -d gitlabhq_production -W
    

    When prompted enter the password you set in the first step for the gitlab_replicator user. If all worked correctly, you should see the database prompt.

  3. Exit the PostgreSQL console:

    \q
    
  4. Edit postgresql.conf to configure the secondary for streaming replication (for Debian/Ubuntu that would be /etc/postgresql/9.x/main/postgresql.conf):

    wal_level = hot_standby
    max_wal_senders = 5
    checkpoint_segments = 10
    wal_keep_segments = 10
    hot_standby = on
    
  5. Restart PostgreSQL for the changes to take effect.

  6. Continue to initiate the replication process.

Step 3. Initiate the replication process

Below we provide a script that connects to the primary server, replicates the database and creates the needed files for replication.

The directories used are the defaults that are set up in Omnibus. If you have changed any defaults or are using a source installation, configure it as you see fit replacing the directories and paths.

Warning: Make sure to run this on the secondary server as it removes all PostgreSQL's data before running pg_basebackup.

  1. SSH into your GitLab secondary server and login as root:

    sudo -i
    
  2. Save the snippet below in a file, let's say /tmp/replica.sh:

    #!/bin/bash
    
    PORT="5432"
    USER="gitlab_replicator"
    echo ---------------------------------------------------------------
    echo WARNING: Make sure this scirpt is run from the secondary server
    echo ---------------------------------------------------------------
    echo
    echo Enter the IP of the primary PostgreSQL server
    read HOST
    echo Enter the password for $USER@$HOST
    read -s PASSWORD
    
    echo Stopping PostgreSQL and all GitLab services
    gitlab-ctl stop
    
    echo Backing up postgresql.conf
    sudo -u gitlab-psql mv /var/opt/gitlab/postgresql/data/postgresql.conf /var/opt/gitlab/postgresql/
    
    echo Cleaning up old cluster directory
    sudo -u gitlab-psql rm -rf /var/opt/gitlab/postgresql/data
    rm -f /tmp/postgresql.trigger
    
    echo Starting base backup as the replicator user
    echo Enter the password for $USER@$HOST
    sudo -u gitlab-psql /opt/gitlab/embedded/bin/pg_basebackup -h $HOST -D /var/opt/gitlab/postgresql/data -U gitlab_replicator -v -x -P
    
    echo Writing recovery.conf file
    sudo -u gitlab-psql bash -c "cat > /var/opt/gitlab/postgresql/data/recovery.conf <<- _EOF1_
      standby_mode = 'on'
      primary_conninfo = 'host=$HOST port=$PORT user=$USER password=$PASSWORD'
      trigger_file = '/tmp/postgresql.trigger'
    _EOF1_
    "
    
    echo Restoring postgresql.conf
    sudo -u gitlab-psql mv /var/opt/gitlab/postgresql/postgresql.conf /var/opt/gitlab/postgresql/data/
    
    echo Starting PostgreSQL and all GitLab services
    gitlab-ctl start
    
  3. Run it with:

    bash /tmp/replica.sh
    

    When prompted, enter the password you set up for the gitlab_replicator user in the first step.

The replication process is now over.

Next steps

Now that the database replication is done, the next step is to configure GitLab.

➤ GitLab Geo configuration

MySQL replication

We don't support MySQL replication for GitLab Geo.