BigW Consortium Gitlab

index.md 5.9 KB
Newer Older
Jacob Vosmaer committed
1 2
# Gitaly

3
[Gitaly](https://gitlab.com/gitlab-org/gitaly) (introduced in GitLab
Jacob Vosmaer committed
4
9.0) is a service that provides high-level RPC access to Git
5
repositories. Gitaly is a mandatory component in GitLab 9.4 and newer.
Jacob Vosmaer committed
6 7 8 9 10 11 12

GitLab components that access Git repositories (gitlab-rails,
gitlab-shell, gitlab-workhorse) act as clients to Gitaly. End users do
not have direct access to Gitaly.

## Configuring Gitaly

13 14
The Gitaly service itself is configured via a TOML configuration file.
This file is documented [in the gitaly
Jacob Vosmaer committed
15 16
repository](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/configuration/README.md).

17 18
To change a Gitaly setting in Omnibus you can use
`gitaly['my_setting']` in `/etc/gitlab/gitlab.rb`. Changes will be applied
Jacob Vosmaer committed
19 20 21
when you run `gitlab-ctl reconfigure`.

```ruby
22
gitaly['prometheus_listen_addr'] = 'localhost:9236'
Jacob Vosmaer committed
23 24
```

25 26
To change a Gitaly setting in installations from source you can edit
`/home/git/gitaly/config.toml`.
Jacob Vosmaer committed
27

28 29
```toml
prometheus_listen_addr = "localhost:9236"
Jacob Vosmaer committed
30 31
```

32
Changes to `/home/git/gitaly/config.toml` are applied when you run `service
Jacob Vosmaer committed
33 34
gitlab restart`.

35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
## Running Gitaly on its own server

> This is an optional way to deploy Gitaly which can benefit GitLab
installations that are larger than a single machine. Most
installations will be better served with the default configuration
used by Omnibus and the GitLab source installation guide.

Starting with GitLab 9.4 it is possible to run Gitaly on a different
server from the rest of the application. This can improve performance
when running GitLab with its repositories stored on an NFS server.

At the moment (GitLab 9.4) Gitaly is not yet a replacement for NFS
because some parts of GitLab still bypass Gitaly when accessing Git
repositories. If you choose to deploy Gitaly on your NFS server you
must still also mount your Git shares on your GitLab application
servers.

Gitaly network traffic is unencrypted so you should use a firewall to
restrict access to your Gitaly server.

Below we describe how to configure a Gitaly server at address
`gitaly.internal:9999` with secret token `abc123secret`. We assume
your GitLab installation has two repository storages, `default` and
`storage1`.

### Client side token configuration

Start by configuring a token on the client side.

Omnibus installations:

```ruby
# /etc/gitlab/gitlab.rb
gitlab_rails['gitaly_token'] = 'abc123secret'
```

Source installations:

```yaml
# /home/git/gitlab/config/gitlab.yml
gitlab:
  gitaly:
    token: 'abc123secret'
```

You need to reconfigure (Omnibus) or restart (source) for these
changes to be picked up.

### Gitaly server configuration

Next, on the Gitaly server, we need to configure storage paths, enable
the network listener and configure the token.

Note: if you want to reduce the risk of downtime when you enable
Jacob Vosmaer committed
89 90 91
authentication you can temporarily disable enforcement, see [the
documentation on configuring Gitaly
authentication](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/configuration/README.md#authentication)
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
.

In most or all cases the storage paths below end in `/repositories`. Check the
directory layout on your Gitaly server to be sure.

Omnibus installations:

```ruby
# /etc/gitlab/gitlab.rb
gitaly['listen_addr'] = '0.0.0.0:9999'
gitaly['auth_token'] = 'abc123secret'
gitaly['storage'] = [
  { 'name' => 'default', 'path' => '/path/to/default/repositories' },
  { 'name' => 'storage1', 'path' => '/path/to/storage1/repositories' },
]
```

Source installations:

```toml
# /home/git/gitaly/config.toml
listen_addr = '0.0.0.0:9999'

[auth]
token = 'abc123secret'

[[storage]
name = 'default'
path = '/path/to/default/repositories'

[[storage]]
name = 'storage1'
path = '/path/to/storage1/repositories'
```

Again, reconfigure (Omnibus) or restart (source).

### Converting clients to use the Gitaly server

Now as the final step update the client machines to switch from using
their local Gitaly service to the new Gitaly server you just
configured. This is a risky step because if there is any sort of
network, firewall, or name resolution problem preventing your GitLab
server from reaching the Gitaly server then all Gitaly requests will
fail.

We assume that your Gitaly server can be reached at
`gitaly.internal:9999` from your GitLab server, and that your GitLab
NFS shares are mounted at `/mnt/gitlab/default` and
`/mnt/gitlab/storage1` respectively.

Omnibus installations:

```ruby
# /etc/gitlab/gitlab.rb
git_data_dirs({
  { 'default' => { 'path' => '/mnt/gitlab/default', 'gitaly_address' => 'tcp://gitlab.internal:9999' } },
  { 'storage1' => { 'path' => '/mnt/gitlab/storage1', 'gitaly_address' => 'tcp://gitlab.internal:9999' } },
})
151 152

gitlab_rails['gitaly_token'] = 'abc123secret'
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
```

Source installations:

```yaml
# /home/git/gitlab/config/gitlab.yml
gitlab:
  repositories:
    storages:
      default:
        path: /mnt/gitlab/default/repositories
        gitaly_address: tcp://gitlab.internal:9999
      storage1:
        path: /mnt/gitlab/storage1/repositories
        gitaly_address: tcp://gitlab.internal:9999
168 169 170

  gitaly:
    token: 'abc123secret'
171 172 173 174 175 176 177 178
```

Now reconfigure (Omnibus) or restart (source). When you tail the
Gitaly logs on your Gitaly server (`sudo gitlab-ctl tail gitaly` or
`tail -f /home/git/gitlab/log/gitaly.log`) you should see requests
coming in. One sure way to trigger a Gitaly request is to clone a
repository from your GitLab server over HTTP.

Jacob Vosmaer committed
179 180
## Disabling or enabling the Gitaly service

181 182 183
If you are running Gitaly [as a remote
service](#running-gitaly-on-its-own-server) you may want to disable
the local Gitaly service that runs on your Gitlab server by default.
Jacob Vosmaer committed
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201

To disable the Gitaly service in your Omnibus installation, add the
following line to `/etc/gitlab/gitlab.rb`:

```ruby
gitaly['enable'] = false
```

When you run `gitlab-ctl reconfigure` the Gitaly service will be
disabled.

To disable the Gitaly service in an installation from source, add the
following to `/etc/default/gitlab`:

```shell
gitaly_enabled=false
```

202
When you run `service gitlab restart` Gitaly will be disabled.