Skip to content

G
gitlab-ce
Commit 1ec29b23 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Simplify README setup for Geo

parent 50db0b98
Expand all Show whitespace changes
Inline Side-by-side
Showing with 133 additions and 531 deletions
doc/gitlab-geo/README.md
View file @ 1ec29b23
......@@ -43,18 +43,14 @@ Keep in mind that:
## Setup instructions
GitLab Geo requires some additional work installing and configuring your
instance, than a normal setup.
There are a couple of things you need to do in order to have one or more GitLab
Geo instances. Follow the steps below in the **exact order** that they appear:
1. Follow the instructions to [install GitLab Enterprise Edition][install-ee]
on the server that will serve as the secondary Geo node, but don't further
configure GitLab as authentication will be handled by the primary node (more
on this in the configuration step).
1. [Setup a database replication](database.md) in `primary <-> secondary (read-only)` topology.
1. [Configure GitLab](configuration.md) and set the primary and secondary nodes.
In order to set up one or more GitLab Geo instances, follow the steps below in
this **exact order**:
1. Follow the first 3 steps to [install GitLab Enterprise Edition][install-ee]
on the server that will serve as the secondary Geo node. Do not login or
set up anything else in the secondary node for the moment.
1. [Setup the database replication](database.md) (`primary <-> secondary (read-only)` topology)
1. [Configure GitLab](configuration.md) to set the primary and secondary nodes.
## After setup
......
doc/gitlab-geo/configuration.md
View file @ 1ec29b23
# GitLab Geo configuration for Omnibus installations
# GitLab Geo configuration
For installations from Source, go to [Source Geo Configuration](source-configuration.md).
> **Important:**
Make sure you have followed the first two steps of the
[Setup instructions](README.md#setup-instructions).
......@@ -11,7 +10,7 @@ up to:
1. Configure the primary node
1. Replicate some required configurations between the primary and the secondaries
1. Start GitLab on the secondary node's machine
1. Start GitLab in the secondary node's machine
1. Configure every secondary node in the primary's Admin screen
After GitLab's instance is online and defined in **Geo Nodes** admin screen,
......@@ -21,15 +20,12 @@ old data from the primary machine (more information below).
## Primary node GitLab setup
>**Notes:**
- You will need to setup your database into a **Primary <-> Secondary (read-only)**
replication topology, and your Primary node should always point to a
database's Primary instance. If you haven't done that already, follow
[database replication](./database.md).
- You will need to setup your database into a **Primary <-> Secondary (read-only)** replication
topology, and your Primary node should always point to a database's Primary
instance. If you haven't done that already, read [database replication](./database.md).
- Only in the Geo nodes admin area of the primary node, will you be adding all
nodes' information (secondary and primary). Do not add anything in the Geo
nodes admin area of the secondaries.
- Each node needs to have the `external_url` in their `gitlab.rb` file properly
set to the real URL or IP address where the other nodes can reach them.
To setup the primary node:
......@@ -52,26 +48,27 @@ In the following table you can see what all these settings mean:
| Setting | Description |
| --------- | ----------- |
| Primary | This marks a Geo Node as primary. There can be only one primary, make sure that you first add the primary node and then all the others. |
| URL | Your instance's full URL, in the same way it is configured in `/etc/gitlab/gitlab.rb` |
| URL | Your instance's full URL, in the same way it is configured in `gitlab.yml` (source based installations) or `/etc/gitlab/gitlab.rb` (omnibus installations). |
|Public Key | The SSH public key of the user that your GitLab instance runs on (unless changed, should be the user `git`). That means that you have to go in each Geo Node separately and create an SSH key pair. See the [SSH key creation][ssh-pair] section. |
## Secondary node GitLab setup
>**Notes:**
- The Geo nodes admin area (**Admin Area > Geo Nodes**) is not used when setting
up the secondary nodes. This is handled at the primary one.
- To install a secondary node, you must follow the normal GitLab Enterprise
Edition installation, with some extra requirements:
1. Follow the [setup database replication](./database.md) instructions.
1. Your secondary node should be allowed to [communicate via HTTP/HTTPS and
>**Note:**
The Geo nodes admin area (**Admin Area > Geo Nodes**) is not used when setting
up the secondary nodes. This is handled at the primary one.
To install a secondary node, you must follow the normal GitLab Enterprise
Edition installation, with some extra requirements:
- You should point your database connection to a [replicated instance](./database.md).
- Your secondary node should be allowed to [communicate via HTTP/HTTPS and
SSH with your primary node (make sure your firewall is not blocking that).
1. Don't make any extra steps you would do for a normal new installation.
1. Run `sudo gitlab-ctl reconfigure` after installing
1. Don't setup any custom authentication or user accounts (this will be
handled by the **primary** node)
1. You need to make sure you restored the database backup (the script in the
database replication setup) and that the primary node PostgreSQL instance is
ready to replicate data.
- Don't make any extra steps you would do for a normal new installation
- Don't setup any custom authentication (this will be handled by the `primary` node)
You need to make sure you restored the database backup (that is part of setting
up replication) and that the primary node PostgreSQL instance is ready to
replicate data.
### Database Encryption Key
......@@ -81,7 +78,8 @@ sensitive data in the database.
Any secondary node must have the **exact same value** for `db_key_base` as
defined in the primary one.
- It is stored at `/etc/gitlab/gitlab-secrets.json`.
- For Omnibus installations it is stored at `/etc/gitlab/gitlab-secrets.json`.
- For installations from source it is stored at `/home/git/gitlab/config/secrets.yml`.
Find that key in the primary node and copy paste its value in the secondaries.
......@@ -114,13 +112,17 @@ The two most obvious issues that replication can have here are:
Getting a new secondary Geo node up and running, will also require the
repositories directory to be synced from the primary node. You can use `rsync`
for that. Assuming `1.2.3.4` is the IP of the primary node, and that you have
[Root Password Login](http://askubuntu.com/questions/469143/how-to-enable-ssh-root-access-on-ubuntu-14-04)
enabled, SSH into the secondary and run:
for that. Assuming `1.2.3.4` is the IP of the primary node, SSH into the
secondary and run:
```bash
sudo rsync -guavrP root@1.2.3.4:/var/opt/gitlab/git-data/repositories/ /var/opt/gitlab/git-data/repositories/
sudo gitlab-ctl reconfigure # to fix directory permissions
# For Omnibus installations
rsync -guavrP root@1.2.3.4:/var/opt/gitlab/git-data/repositories/ /var/opt/gitlab/git-data/repositories/
gitlab-ctl reconfigure # to fix directory permissions
# For installations from source
rsync -guavrP root@1.2.3.4:/home/git/repositories/ /home/git/repositories/
chmod ug+rwX,o-rwx /home/git/repositories
```
If this step is not followed, the secondary node will eventually clone and
......@@ -140,7 +142,11 @@ On the secondary node where the database is [already replicated](./database.md),
run:
```
sudo gitlab-rake gitlab:shell:setup
# For Omnibus installations
gitlab-rake gitlab:shell:setup
# For source installations
sudo -u git -H bundle exec rake gitlab:shell:setup RAILS_ENV=production
```
This will enable `git` operations to authorize against your existing users.
......@@ -167,17 +173,20 @@ When adding a new Geo node, you must provide an SSH public key of the user that
your GitLab instance runs on (unless changed, should be the user `git`). This
user will act as a "normal user" who fetches from the primary Geo node.
1. Run the command below on each server that will be a Geo node, and leave the
password blank:
1. Run the command below on each server that will be a Geo node:
```bash
sudo -u git -H ssh-keygen
```
1. Get the contents of `id_rsa.pub` that was just created:
1. Get the contents of `id_rsa.pub` the was just created:
```
# Omnibus installations
sudo -u git cat /var/opt/gitlab/.ssh/id_rsa.pub
# Installations from source
sudo -u git cat /home/git/.ssh/id_rsa.pub
```
1. Copy them to the admin area of the **primary** node (**Admin Area > Geo Nodes**).
......@@ -207,8 +216,7 @@ Host example.com # The FQDN of the primary Geo node
### Add the primary node to the `known_hosts` file of the secondary nodes
>**Note:**
This operation is only needed for the secondary nodes, and needs to be done
after adding the SSH key of the secondary node as a Geo node on the primary.
This operation is only needed for the secondary nodes.
---
......@@ -224,13 +232,14 @@ sudo -u git -H ssh git@<primary-node-url>
Replace `<primary-node-url>` with the FQDN of the primary node. You can verify
that the fingerprint was added by checking:
- `/var/opt/gitlab/.ssh/known_hosts`
- `/var/opt/gitlab/.ssh/known_hosts` for Omnibus installations or
- `/home/git/.ssh/known_hosts` for installations from source
## Troubleshooting
Setting up Geo requires careful attention to details and sometimes it's easy to
miss a step. Here is a checklist of questions you should ask to try to detect
where you have to fix:
where you have to fix (all commands and path locations are for Omnibus installs):
- Is Postgres replication working?
- Are my nodes pointing to the correct database instance?
......@@ -244,7 +253,7 @@ where you have to fix:
- To check if node on current machine is correctly detected type:
```
sudo gitlab-rails runner "puts Gitlab::Geo.current_node.inspect"
sudo gitlab-rails runner "Gitlab::Geo.current_node"
```
and expect something like:
......
doc/gitlab-geo/database.md
View file @ 1ec29b23
# GitLab Geo database replication for Omnibus installations
For installations from source, go to [source database replication](source-database.md).
# 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.
The GitLab primary node where the write operations happen will connect to the
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).
......@@ -30,8 +28,12 @@ and `secondary` as either `slave` or `standby` server (read-only).
The following guide assumes that:
- You have a primary server already set up, and you have a new secondary server
set up on the same OS. Make sure the GitLab version is the same on all nodes.
- You are using PostgreSQL 9.1 or later which includes the
[`pg_basebackup` tool][pgback]. As of this writing, the latest Omnibus
packages (8.5) have version 9.2.
- You have a primary server already set up, running PostgreSQL 9.2.x, and you
have a new secondary server set up on the same OS and PostgreSQL version. If
you are using Omnibus, make sure the GitLab version is the same on all nodes.
- The IP of the primary server for our examples will be `1.2.3.4`, whereas the
secondary's IP will be `5.6.7.8`.
......@@ -39,6 +41,48 @@ The following guide assumes that:
### PostgreSQL - Configure the primary server
**For installations from source**
1. Login as root and create a replication user:
```bash
sudo -u postgres psql -c "CREATE USER gitlab_replicator REPLICATION ENCRYPTED PASSWORD 'thepassword';"
```
1. Edit `postgresql.conf` to configure the primary server for streaming replication
(for Debian/Ubuntu that would be `/etc/postgresql/9.2/main/postgresql.conf`):
```bash
listen_address = '1.2.3.4'
wal_level = hot_standby
max_wal_senders = 5
checkpoint_segments = 10
wal_keep_segments = 10
hot_standby = on
```
Edit the `wal` values as you see fit.
1. 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.2/main/pg_hba.conf`):
```bash
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.
1. Restart PostgreSQL for the changes to take effect
---
**For Omnibus installations**
1. Omnibus GitLab has already a replicator user called `gitlab_replicator`.
You must set its password manually:
......@@ -66,36 +110,50 @@ The following guide assumes that:
Edit the `wal` values as you see fit.
1. Run `sudo gitlab-ctl reconfigure` for the changes to take effect.
1. [Reconfigure GitLab][] for the changes to take effect.
---
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. If it worked, one of the lines should look like this, with your
IP address instead of our example `1.2.3.4`:
```
tcp 0 0 1.2.3.4:5432 0.0.0.0:* LISTEN -
```
This next step requires that `sudo gitlab-ctl reconfigure` has run at least once
on the secondary server.
public IP.
Test that the remote connection works by going to the secondary server and
running:
```
# For Omnibus installations
sudo -u gitlab-psql /opt/gitlab/embedded/bin/psql -h 1.2.3.4 -U gitlab_replicator -d gitlabhq_production -W
# For source installations
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. Run `\q` to exit.
prompt.
### PostgreSQL - Configure the secondary server
**For installations from source**
1. Edit `postgresql.conf` to configure the secondary for streaming replication
(for Debian/Ubuntu that would be `/etc/postgresql/9.2/main/postgresql.conf`):
```bash
wal_level = hot_standby
max_wal_senders = 5
checkpoint_segments = 10
wal_keep_segments = 10
hot_standby = on
```
1. Restart PostgreSQL for the changes to take effect
---
**For Omnibus installations**
1. Edit `/etc/gitlab/gitlab.rb` and add the following:
```ruby
......@@ -105,7 +163,7 @@ prompt. Run `\q` to exit.
postgresql['hot_standby'] = "on"
```
1. Run `sudo gitlab-ctl reconfigure` for the changes to take effect.
1. [Reconfigure GitLab][] for the changes to take effect.
### PostgreSQL - Initiate the replication process
......
doc/gitlab-geo/source-configuration.md deleted 100644 → 0
View file @ 50db0b98
This diff is collapsed.
doc/gitlab-geo/source-database.md deleted 100644 → 0
View file @ 50db0b98
# GitLab Geo database replication for Source installations
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.
The GitLab primary node where the write operations happen will connect to the
`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).
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**
- [PostgreSQL replication](#postgresql-replication)
- [PostgreSQL - Configure the primary server](#postgresql-configure-the-primary-server)
- [PostgreSQL - Configure the secondary server](#postgresql-configure-the-secondary-server)
- [PostgreSQL - Initiate the replication process](#postgresql-initiate-the-replication-process)
- [MySQL replication](#mysql-replication)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## PostgreSQL replication
The following guide assumes that:
- You are using PostgreSQL 9.1 or later which includes the
[`pg_basebackup` tool][pgback]. As of this writing, the latest Omnibus
packages (8.5) have version 9.2.
- You have a primary server already set up, running PostgreSQL 9.2.x, and you
have a new secondary server set up on the same OS and PostgreSQL version.
- The IP of the primary server for our examples will be `1.2.3.4`, whereas the
secondary's IP will be `5.6.7.8`.
[pgback]: http://www.postgresql.org/docs/9.2/static/app-pgbasebackup.html
### PostgreSQL - Configure the primary server
1. Login as root and create a replication user:
```bash
sudo -u postgres psql -c "CREATE USER gitlab_replicator REPLICATION ENCRYPTED PASSWORD 'thepassword';"
```
1. Edit `postgresql.conf` to configure the primary server for streaming replication
(for Debian/Ubuntu that would be `/etc/postgresql/9.2/main/postgresql.conf`):
```bash
listen_address = '1.2.3.4'
wal_level = hot_standby
max_wal_senders = 5
checkpoint_segments = 10
wal_keep_segments = 10
hot_standby = on
```
Edit the `wal` values as you see fit.
1. 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.2/main/pg_hba.conf`):
```bash
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.
1. Restart PostgreSQL for the changes to take effect
---
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.
Test that the remote connection works by going to the secondary server and
running:
```
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. Run `\q` to exit.
### PostgreSQL - Configure the secondary server
**For installations from source**
1. Edit `postgresql.conf` to configure the secondary for streaming replication
(for Debian/Ubuntu that would be `/etc/postgresql/9.2/main/postgresql.conf`):
```bash
wal_level = hot_standby
max_wal_senders = 5
checkpoint_segments = 10
wal_keep_segments = 10
hot_standby = on
```
1. Restart PostgreSQL for the changes to take effect
---
### PostgreSQL - 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. 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`.
```bash
#!/bin/bash
PORT="5432"
USER="gitlab_replicator"
echo Enter ip of primary postgresql server
read HOST
echo Enter password for $USER@$HOST
read -s PASSWORD
echo Stopping PostgreSQL
gitlab-ctl stop
echo Backup 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 replicator
echo Enter 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 Restore postgresql.conf
sudo -u gitlab-psql mv /var/opt/gitlab/postgresql/postgresql.conf /var/opt/gitlab/postgresql/data/
echo Starting PostgreSQL
gitlab-ctl start
```
When prompted, enter the password you set up for the `gitlab_replicator` user.
## MySQL replication
We don't support MySQL replication for GitLab Geo.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7