requirements.md 10.8 KB
Newer Older
Marin Jankovski's avatar
Marin Jankovski committed
1 2 3
# Requirements

## Operating Systems
4

5
### Supported Unix distributions
randx's avatar
randx committed
6

7 8
- Ubuntu
- Debian
9
- CentOS
10
- openSUSE
11
- Red Hat Enterprise Linux (please use the CentOS packages and instructions)
12 13
- Scientific Linux (please use the CentOS packages and instructions)
- Oracle Linux (please use the CentOS packages and instructions)
14

15 16
For the installations options please see [the installation page on the GitLab website](https://about.gitlab.com/installation/).

17
### Unsupported Unix distributions
18 19

- Arch Linux
randx's avatar
randx committed
20
- Fedora
21
- FreeBSD
22 23
- Gentoo
- macOS
randx's avatar
randx committed
24

25
On the above unsupported distributions is still possible to install GitLab yourself.
26
Please see the [installation from source guide](installation.md) and the [installation guides](https://about.gitlab.com/installation/) for more information.
27

28
### Non-Unix operating systems such as Windows
29

30
GitLab is developed for Unix operating systems.
31
It does **not** run on Windows, and we have no plans to support it in the near future. For the latest development status view this [issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/46567).
32
Please consider using a virtual machine to run GitLab.
33

34
## Ruby versions
randx's avatar
randx committed
35

36
GitLab requires Ruby (MRI) 2.5. Support for Ruby versions below 2.5 (2.3, 2.4) will stop with GitLab 11.6.
37

dosire's avatar
dosire committed
38
You will have to use the standard MRI implementation of Ruby.
Evan Read's avatar
Evan Read committed
39
We love [JRuby](https://www.jruby.org/) and [Rubinius](https://rubinius.com) but GitLab
40
needs several Gems that have native extensions.
randx's avatar
randx committed
41

42
## Hardware requirements
43

44 45
### Storage

46
The necessary hard drive space largely depends on the size of the repos you want to store in GitLab but as a *rule of thumb* you should have at least as much free space as all your repos combined take up.
47 48 49 50 51 52 53

If you want to be flexible about growing your hard drive space in the future consider mounting it using LVM so you can add more hard drives when you need them.

Apart from a local hard drive you can also mount a volume that supports the network file system (NFS) protocol. This volume might be located on a file server, a network attached storage (NAS) device, a storage area network (SAN) or on an Amazon Web Services (AWS) Elastic Block Store (EBS) volume.

If you have enough RAM memory and a recent CPU the speed of GitLab is mainly limited by hard drive seek times. Having a fast drive (7200 RPM and up) or a solid state drive (SSD) will improve the responsiveness of GitLab.

54 55
NOTE: **Note:** Since file system performance may affect GitLab's overall performance, we do not recommend using EFS for storage. See the [relevant documentation](../administration/high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs) for more details.

56
### CPU
57

Ian Lee's avatar
Ian Lee committed
58
- 1 core supports up to 100 users but the application can be a bit slower due to having all workers and background jobs running on the same core
dosire's avatar
dosire committed
59 60 61
- **2 cores** is the **recommended** number of cores and supports up to 500 users
- 4 cores supports up to 2,000 users
- 8 cores supports up to 5,000 users
62 63 64
- 16 cores supports up to 10,000 users
- 32 cores supports up to 20,000 users
- 64 cores supports up to 40,000 users
65
- More users? Run it on [multiple application servers](https://about.gitlab.com/high-availability/)
66

67
### Memory
68

69
You need at least 8GB of addressable memory (RAM + swap) to install and use GitLab!
70
The operating system and any other running applications will also be using memory
Ahmad Sherif's avatar
Ahmad Sherif committed
71
so keep in mind that you need at least 4GB available before running GitLab. With
72 73
less memory GitLab will give strange errors during the reconfigure run and 500
errors during usage.
74

75 76
- 4GB RAM + 4GB swap supports up to 100 users but it will be very slow
- **8GB RAM** is the **recommended** memory size for all installations and supports up to 100 users
Ahmad Sherif's avatar
Ahmad Sherif committed
77 78 79 80 81
- 16GB RAM supports up to 2,000 users
- 32GB RAM supports up to 4,000 users
- 64GB RAM supports up to 8,000 users
- 128GB RAM supports up to 16,000 users
- 256GB RAM supports up to 32,000 users
82
- More users? Run it on [multiple application servers](https://about.gitlab.com/high-availability/)
83

84
We recommend having at least [2GB of swap on your server](https://askubuntu.com/a/505344/310789), even if you currently have
Chris Spicer's avatar
Chris Spicer committed
85
enough available RAM. Having swap will help reduce the chance of errors occurring
René Genz's avatar
René Genz committed
86
if your available memory changes. We also recommend [configuring the kernel's swappiness setting](https://askubuntu.com/a/103916)
87 88
to a low value like `10` to make the most of your RAM while still having the swap
available when needed.
89

90
Notice: The 25 workers of Sidekiq will show up as separate processes in your process overview (such as `top` or `htop`) but they share the same RAM allocation since Sidekiq is a multithreaded application. Please see the section below about Unicorn workers for information about how many you need of those.
91

92 93
## Database

94 95 96 97
The server running the database should have _at least_ 5-10 GB of storage
available, though the exact requirements depend on the size of the GitLab
installation (e.g. the number of users, projects, etc).

98 99
We currently support the following databases:

sytses's avatar
sytses committed
100
- PostgreSQL (highly recommended)
sytses's avatar
sytses committed
101
- MySQL/MariaDB (strongly discouraged, not all GitLab features are supported, no support for [MySQL/MariaDB GTID](https://mariadb.com/kb/en/mariadb/gtid/))
102

sytses's avatar
sytses committed
103
We highly recommend the use of PostgreSQL instead of MySQL/MariaDB as not all
sytses's avatar
sytses committed
104
features of GitLab work with MySQL/MariaDB:
105

106
1. MySQL support for subgroups was [dropped with GitLab 9.3][post].
107
   See [issue #30472][30472] for more information.
108
1. Geo does [not support MySQL](https://docs.gitlab.com/ee/administration/geo/replication/database.html#mysql-replication). This means no supported Disaster Recovery solution if using MySQL. **[PREMIUM ONLY]**
109
1. [Zero downtime migrations](../update/README.md#upgrading-without-downtime) do not work with MySQL.
110 111 112
1. GitLab [optimizes the loading of dashboard events](https://gitlab.com/gitlab-org/gitlab-ce/issues/31806) using [PostgreSQL LATERAL JOINs](https://blog.heapanalytics.com/postgresqls-powerful-new-join-type-lateral/).
1. In general, SQL optimized for PostgreSQL may run much slower in MySQL due to
   differences in query planners. For example, subqueries that work well in PostgreSQL
113 114 115 116
   may not be [performant in MySQL](https://dev.mysql.com/doc/refman/5.7/en/optimizing-subqueries.html).
1. Binary column index length is limited to 20 bytes. This is accomplished with [a hack](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/initializers/mysql_set_length_for_binary_indexes.rb).
1. MySQL requires a variety of hacks to increase limits on various columns, [for example](https://gitlab.com/gitlab-org/gitlab-ce/issues/49583).
1. [The milestone filter runs slower queries on MySQL](https://gitlab.com/gitlab-org/gitlab-ce/issues/51173#note_99391731).
sytses's avatar
sytses committed
117
1. We expect this list to grow over time.
118

119
Existing users using GitLab with MySQL/MariaDB are advised to
120
[migrate to PostgreSQL](../update/mysql_to_postgresql.md) instead.
121

122
[30472]: https://gitlab.com/gitlab-org/gitlab-ce/issues/30472
123
[post]: https://about.gitlab.com/2017/06/22/gitlab-9-3-released/#dropping-support-for-subgroups-in-mysql
124

125 126
### PostgreSQL Requirements

Nick Thomas's avatar
Nick Thomas committed
127
As of GitLab 10.0, PostgreSQL 9.6 or newer is required, and earlier versions are
128
not supported. We highly recommend users to use PostgreSQL 9.6 as this
129
is the PostgreSQL version used for development and testing.
130

131 132 133 134
Users using PostgreSQL must ensure the `pg_trgm` extension is loaded into every
GitLab database. This extension can be enabled (using a PostgreSQL super user)
by running the following query for every database:

135 136 137
```
CREATE EXTENSION pg_trgm;
```
138 139 140 141

On some systems you may need to install an additional package (e.g.
`postgresql-contrib`) for this extension to become available.

142 143 144 145 146 147 148 149
#### Additional requirements for GitLab Geo

If you are using [GitLab Geo](https://docs.gitlab.com/ee/development/geo.html), the [tracking database](https://docs.gitlab.com/ee/development/geo.html#geo-tracking-database) also requires the `postgres_fdw` extension.

```
CREATE EXTENSION postgres_fdw;
```

150 151 152 153 154 155 156 157 158 159
## Unicorn Workers

It's possible to increase the amount of unicorn workers and this will usually help to reduce the response time of the applications and increase the ability to handle parallel requests.

For most instances we recommend using: CPU cores + 1 = unicorn workers.
So for a machine with 2 cores, 3 unicorn workers is ideal.

For all machines that have 2GB and up we recommend a minimum of three unicorn workers.
If you have a 1GB machine we recommend to configure only two Unicorn workers to prevent excessive swapping.

160
To change the Unicorn workers when you have the Omnibus package (which defaults to the recommendation above) please see [the Unicorn settings in the Omnibus GitLab documentation](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/doc/settings/unicorn.md#unicorn-settings).
161

162 163 164
## Redis and Sidekiq

Redis stores all user sessions and the background task queue.
Sytse Sijbrandij's avatar
Sytse Sijbrandij committed
165
The storage requirements for Redis are minimal, about 25kB per user.
166 167
Sidekiq processes the background jobs with a multithreaded process.
This process starts with the entire Rails stack (200MB+) but it can grow over time due to memory leaks.
Ben Bodenmiller's avatar
Ben Bodenmiller committed
168
On a very active server (10,000 active users) the Sidekiq process can use 1GB+ of memory.
169

170 171
## Prometheus and its exporters

172 173 174 175
As of Omnibus GitLab 9.0, [Prometheus](https://prometheus.io) and its related
exporters are enabled by default, to enable easy and in depth monitoring of
GitLab. Approximately 200MB of memory will be consumed by these processes, with
default settings.
176

177 178
If you would like to disable Prometheus and it's exporters or read more information
about it, check the [Prometheus documentation](../administration/monitoring/prometheus/index.md).
179

180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197
## GitLab Runner

We strongly advise against installing GitLab Runner on the same machine you plan
to install GitLab on. Depending on how you decide to configure GitLab Runner and
what tools you use to exercise your application in the CI environment, GitLab
Runner can consume significant amount of available memory.

Memory consumption calculations, that are available above, will not be valid if
you decide to run GitLab Runner and the GitLab Rails application on the same
machine.

It is also not safe to install everything on a single machine, because of the
[security reasons] - especially when you plan to use shell executor with GitLab
Runner.

We recommend using a separate machine for each GitLab Runner, if you plan to
use the CI features.

198
[security reasons]: https://gitlab.com/gitlab-org/gitlab-runner/blob/master/docs/security/index.md
199

Ben Bodenmiller's avatar
Ben Bodenmiller committed
200
## Supported web browsers
201

202 203 204 205 206 207 208
We support the current and the previous major release of:

- Firefox
- Chrome/Chromium
- Safari
- Microsoft Edge
- Internet Explorer 11
209

210
Each time a new browser version is released, we begin supporting that version and stop supporting the third most recent version.
211 212 213

Note: We do not support running GitLab with JavaScript disabled in the browser and have no plans of supporting that
in the future because we have features such as Issue Boards which require JavaScript extensively.