README.md 7.52 KB
Newer Older
1 2 3 4 5
# Configuring Gitaly

This document describes how to configure the Gitaly server
application.

6 7 8
Gitaly is configured via a [TOML](https://github.com/toml-lang/toml)
configuration file. Where this TOML file is located and how you should
edit it depend on how you installed GitLab. See:
9
https://docs.gitlab.com/ce/administration/gitaly/
10

11 12 13
The configuration file is passed as an argument to the `gitaly`
executable. This is usually done by either omnibus-gitlab or your init
script.
14 15

```
16
gitaly /path/to/config.toml
17 18
```

19
## Format
20 21 22 23

```toml
socket_path = "/path/to/gitaly.sock"
listen_addr = ":8081"
24
bin_dir = "/path/to/gitaly-executables"
25 26
prometheus_listen_addr = ":9236"

Jacob Vosmaer's avatar
Jacob Vosmaer committed
27
[auth]
28
# transitioning = false
Jacob Vosmaer's avatar
Jacob Vosmaer committed
29 30
# token = "abc123def456......."

31 32 33 34 35 36 37 38 39 40 41 42 43 44
[[storage]]
path = "/path/to/storage/repositories"
name = "my_shard"

# Gitaly may serve from multiple storages
#[[storage]]
#name = "other_storage"
#path = "/path/to/other/repositories"
```

|name|type|required|notes|
|----|----|--------|-----|
|socket_path|string|see notes|A path which gitaly should open a Unix socket. Required unless listen_addr is set|
|listen_addr|string|see notes|TCP address for Gitaly to listen on (See #GITALY_LISTEN_ADDR). Required unless socket_path is set|
45
|bin_dir|string|yes|Directory containing Gitaly's executables|
46 47 48
|prometheus_listen_addr|string|no|TCP listen address for Prometheus metrics. If not set, no Prometheus listener is started|
|storage|array|yes|An array of storage shards|

Jacob Vosmaer's avatar
Jacob Vosmaer committed
49 50 51 52 53 54 55 56 57 58 59 60 61 62
### Authentication

Gitaly can be configured to reject requests that do not contain a
specific bearer token in their headers. This is a security measure to
be used when serving requests over TCP.

Authentication is disabled when the token setting in config.toml is absent or the empty string.

```toml
[auth]
# Non-empty token: this enables authentication.
token = "the secret token"
```

63
It is possible to temporarily disable authentication with the 'transitioning'
Jacob Vosmaer's avatar
Jacob Vosmaer committed
64 65 66 67
setting. This allows you to monitor (see below) if all clients are
authenticating correctly without causing a service outage for clients
that are not configured correctly yet.

68
> **Warning:** Remember to disable 'transitioning' when you are done
Jacob Vosmaer's avatar
Jacob Vosmaer committed
69 70 71 72 73
changing your token settings.

```toml
[auth]
token = "the secret token"
74
transitioning = true
Jacob Vosmaer's avatar
Jacob Vosmaer committed
75 76 77
```

All authentication attempts are counted in Prometheus under
78
the `gitaly_authentications_total` metric.
Jacob Vosmaer's avatar
Jacob Vosmaer committed
79

80 81
### Storage

Jacob Vosmaer's avatar
Jacob Vosmaer committed
82 83 84
GitLab repositories are grouped into 'storages'. These are directories
(e.g. `/home/git/repositories`) containing bare repositories managed
by GitLab , with names (e.g. `default`).
85 86 87 88 89 90

These names and paths are also defined in the `gitlab.yml`
configuration file of gitlab-ce (or gitlab-ee). When you run Gitaly on
the same machine as gitlab-ce, which is the default and recommended
configuration, storage paths defined in Gitaly's config.toml must
match those in gitlab.yml.
91 92 93 94 95

|name|type|required|notes|
|----|----|--------|-----|
|path|string|yes|Path to storage shard|
|name|string|yes|Name of storage shard|
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
### Git

The following values can be set in the `[git]` section of the configuration file:

|name|type|required|notes|
|----|----|--------|-----|
|bin_path|string|no|Path to git binary. If not set, will be resolved using PATH.|
|catfile_cache_size|integer|no|Maximum number of cached cat-file processes (see below). Default 100.|

#### cat-file cache

A lot of Gitaly RPC's need to look up Git objects from repositories.
Most of the time we use `git cat-file --batch` processes for that. For
the sake of performance, Gitaly can re-use thse `git cat-file` processes
across RPC calls. Previously used processes are kept around in a "git
cat-file cache". In order to control how much system resources this uses
we have a maximum number of cat-file processes that can go into the
cache.

The default limit is 100 "catfiles", which constitute a pair of
`git cat-file --batch` and `git cat-file --batch-check` processes. If
you are seeing errors complaining about "too many open files", or an
inability to create new processes, you may want to lower this limit.

Ideally the number should be large enough to handle normal (peak)
traffic. If you raise the limit you should measure the cache hit ratio
before and after. If the hit ratio does not improve, the higher limit is
probably not making a meaningful difference. Here is an example
prometheus query to see the hit rate:

```
sum(rate(gitaly_catfile_cache_total{type="hit"}[5m])) / sum(rate(gitaly_catfile_cache_total{type=~"(hit)|(miss)"}[5m]))
```

131 132 133 134 135 136 137
### gitaly-ruby

A Gitaly process uses one or more gitaly-ruby helper processes to
execute RPC's implemented in Ruby instead of Go. The `[gitaly-ruby]`
section of the config file contains settings for these helper processes.

These processes are known to occasionally suffer from memory leaks.
138
Gitaly restarts its gitaly-ruby helpers when their memory exceeds the
139 140 141 142 143 144 145 146
max\_rss limit.

|name|type|required|notes|
|----|----|--------|-----|
|dir|string|yes|Path to where gitaly-ruby is installed (needed to boot the process).|
|max_rss|integer|no|Resident set size limit that triggers a gitaly-ruby restart, in bytes. Default 300MB.|
|graceful_restart_timeout|string|no|Grace period to allow a gitaly-ruby process to finish ongoing requests. Default 10 minutes ("10m").|
|restart_delay|string|no|Time memory must be high before a restart is triggered, in seconds. Default 5 minutes ("5m").|
147
|num_workers|integer|no|Number of gitaly-ruby worker processes. Try increasing this number in case of ResourceExhausted errors. Default 2, minimum 2.|
148
|linguist_languages_path|string|no|Override for dynamic languages.json discovery. Default: "" (use dynamic discovery).|
149

150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
### gitlab-shell

For historical reasons
[gitlab-shell](https://gitlab.com/gitlab-org/gitlab-shell) contains
the Git hooks that allow GitLab to validate and react to Git pushes.
Because Gitaly "owns" Git pushes, gitlab-shell must therefore be
installed alongside Gitaly. We hope this will be [simplified in the
future](https://gitlab.com/gitlab-org/gitaly/issues/1226).

```toml
[gitlab-shell]
dir = "/home/git/gitlab-shell"
```

|name|type|required|notes|
|----|----|--------|-----|
|dir|string|yes|The directory where gitlab-shell is installed.|

168 169
### Logging

170 171
Example:

172
```toml
173 174 175 176
[logging]
level = "warn"
```

177 178 179
|name|type|required|notes|
|----|----|--------|-----|
|format|string|no|Log format: "text" or "json". Default: "text"|
180
|level|string|no| Log level: "debug", "info", "warn", "error", "fatal", or "panic". Default: "info"|
181
|sentry_dsn|string|no|Sentry DSN for exception monitoring|
182
|sentry_environment|string|no|Sentry Environment for exception monitoring|
183 184
|ruby_sentry_dsn|string|no|Sentry DSN for gitaly-ruby exception monitoring|

Jacob Vosmaer's avatar
Jacob Vosmaer committed
185
## Environment variables
186 187 188

### GITALY_SOCKET_PATH

Jacob Vosmaer's avatar
Jacob Vosmaer committed
189 190
Required unless GITALY_LISTEN_ADDR is set. Overrides `socket_path` in
config.toml. Deprecated; use config.toml.
191 192 193 194 195 196 197 198 199

A path at which Gitaly should open a Unix socket. Example value:

```
GITALY_SOCKET_PATH=/home/git/gitlab/tmp/sockets/private/gitaly.socket
```

### GITALY_LISTEN_ADDR

Jacob Vosmaer's avatar
Jacob Vosmaer committed
200 201
Required unless GITALY_SOCKET_PATH is set. Overrides `listen_addr` in
config.toml. Deprecated; use config.toml.
202 203 204 205 206 207 208 209 210 211 212 213 214 215

TCP address for Gitaly to listen on. Note: at the moment Gitaly does
not offer any form of authentication. When you use a TCP listener you
must use firewalls or other network-based security to restrict access
to Gitaly.

Example value:

```
GITALY_LISTEN_ADDR=localhost:1234
```

### GITALY_PROMETHEUS_LISTEN_ADDR

Jacob Vosmaer's avatar
Jacob Vosmaer committed
216 217
Optional. Overrides `prometheus_listen_addr` in config.toml.
Deprecated; use config.toml.
218 219 220 221 222 223 224

TCP listen address for Prometheus metrics. When missing or empty, no
Prometheus listener is started.

```
GITALY_PROMETHEUS_LISTEN_ADDR=localhost:9236
```