README.md 12.2 KB
Newer Older
1
# Omnibus GitLab
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
2

3
4
## Description

dosire's avatar
dosire committed
5
6
This project creates full-stack platform-specific [downloadable packages for GitLab][downloads].
For other installation options please see the
7
[GitLab installation page][installation].
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
8

9
10
11
12
13
14
## Canonical source

The source of omnibus-gitlab is [hosted on
GitLab.com](https://gitlab.com/gitlab-org/omnibus-gitlab) and there are mirrors
to make contributing as easy as possible.

Sid Sijbrandij's avatar
Sid Sijbrandij committed
15
## Documentation
16

Sid Sijbrandij's avatar
Sid Sijbrandij committed
17
The documentation overview is in the [readme in the doc directory](doc/README.md).
18

19
20
## Omnibus fork

21
Omnibus GitLab is using a fork of [omnibus project](https://github.com/chef/omnibus).  For additional information see the comments in the [Gemfile](/Gemfile).
22

Marcel Amirault's avatar
Marcel Amirault committed
23
## Deprecated links
24

25
*We left the links below in the readme to preserve old links, but please use the [readme in the doc directory](doc/README.md) to browse the complete documentation.*
26

27
28
29
30
## Contributing

Please see the [contribution guidelines](CONTRIBUTING.md)

31
32
33
34
35
36
## Installation

Please follow the steps on the [downloads page][downloads].

### After installation

37
Your GitLab instance should be reachable over HTTP at the IP or hostname of your
38
server. You can login as an admin user with username `root` and password `5iveL!fe`.
39

40
41
See [doc/maintenance/README.md](doc/maintenance/README.md) for useful commands
to control/debug your GitLab instance.
42

43
### Configuration options
44

45
See [doc/settings/configuration.md](doc/settings/configuration.md).
46

Marcel Amirault's avatar
Marcel Amirault committed
47
#### Configuring the external URL for GitLab
48

49
See [doc/settings/configuration.md](doc/settings/configuration.md#configuring-the-external-url-for-gitlab).
50

Marcel Amirault's avatar
Marcel Amirault committed
51
#### Storing Git data in an alternative directory
dosire's avatar
dosire committed
52

53
See [doc/settings/configuration.md](doc/settings/configuration.md#storing-git-data-in-an-alternative-directory).
54

Marcel Amirault's avatar
Marcel Amirault committed
55
#### Changing the name of the Git user / group
56

57
See [doc/settings/configuration.md](doc/settings/configuration.md#changing-the-name-of-the-git-user-group).
58

Marcel Amirault's avatar
Marcel Amirault committed
59
#### Setting up LDAP sign-in
60

61
See [doc/settings/ldap.md](doc/settings/ldap.md).
dosire's avatar
dosire committed
62

Marcel Amirault's avatar
Marcel Amirault committed
63
#### Enable HTTPS
64

65
See [doc/settings/nginx.md](doc/settings/nginx.md#enable-https).
66

Marcel Amirault's avatar
Marcel Amirault committed
67
#### Redirect `HTTP` requests to `HTTPS`
68

69
See [doc/settings/nginx.md](doc/settings/nginx.md#redirect-http-requests-to-https).
70

Marcel Amirault's avatar
Marcel Amirault committed
71
#### Change the default port and the ssl certificate locations
72

73
See [doc/settings/nginx.md](doc/settings/nginx.md#change-the-default-port-and-the-ssl-certificate-locations).
74

Marcel Amirault's avatar
Marcel Amirault committed
75
#### Use non-packaged web-server
76

77
For using an existing Nginx, Passenger, or Apache webserver see [doc/settings/nginx.md](doc/settings/nginx.md#using-a-non-bundled-web-server).
78

Marcel Amirault's avatar
Marcel Amirault committed
79
#### Using a non-packaged PostgreSQL database management server
80

81
To connect to an external PostgreSQL DBMS see [doc/settings/database.md](doc/settings/database.md)
82

Marcel Amirault's avatar
Marcel Amirault committed
83
#### Using a non-packaged Redis instance
84

85
See [doc/settings/redis.md](doc/settings/redis.md).
86

Marcel Amirault's avatar
Marcel Amirault committed
87
#### Adding ENV Vars to the Gitlab Runtime Environment
Jacob Vosmaer's avatar
Jacob Vosmaer committed
88

89
90
See
[doc/settings/environment-variables.md](doc/settings/environment-variables.md).
Jacob Vosmaer's avatar
Jacob Vosmaer committed
91

Marcel Amirault's avatar
Marcel Amirault committed
92
#### Changing gitlab.yml settings
93

94
See [doc/settings/gitlab.yml.md](doc/settings/gitlab.yml.md).
95

Marcel Amirault's avatar
Marcel Amirault committed
96
#### Specify numeric user and group identifiers
97

98
See [doc/settings/configuration.md](doc/settings/configuration.md#specify-numeric-user-and-group-identifiers).
99

Marcel Amirault's avatar
Marcel Amirault committed
100
#### Sending application email via SMTP
101

102
See [doc/settings/smtp.md](doc/settings/smtp.md).
103

Marcel Amirault's avatar
Marcel Amirault committed
104
#### Omniauth (Google, Twitter, GitHub login)
Jacob Vosmaer's avatar
Jacob Vosmaer committed
105

106
Omniauth configuration is documented in
107
[docs.gitlab.com](https://docs.gitlab.com/ee/integration/omniauth.html).
108

Marcel Amirault's avatar
Marcel Amirault committed
109
#### Adjusting Unicorn settings
110

111
See [doc/settings/unicorn.md](doc/settings/unicorn.md).
112

Marcel Amirault's avatar
Marcel Amirault committed
113
#### Setting the NGINX listen address or addresses
114

115
See [doc/settings/nginx.md](doc/settings/nginx.md).
116

Marcel Amirault's avatar
Marcel Amirault committed
117
#### Inserting custom NGINX settings into the GitLab server block
118

119
See [doc/settings/nginx.md](doc/settings/nginx.md).
120

Marcel Amirault's avatar
Marcel Amirault committed
121
#### Inserting custom settings into the NGINX config
122

123
See [doc/settings/nginx.md](doc/settings/nginx.md).
124

Marcel Amirault's avatar
Marcel Amirault committed
125
#### Only start omnibus-gitlab services after a given filesystem is mounted
126
127
128

See [doc/settings/configuration.md](doc/settings/configuration.md#only-start-omnibus-gitlab-services-after-a-given-filesystem-is-mounted).

129
### Updating
130

131
132
Instructions for updating your Omnibus installation and upgrading from a manual
installation are in the [update doc](doc/update/README.md).
133

134
### Uninstalling omnibus-gitlab
135

Ben Bodenmiller's avatar
Ben Bodenmiller committed
136
137
138
139
To remove all users and groups created by omnibus-gitlab, before removing the gitlab package (with `dpkg` or `yum`) run `sudo gitlab-ctl remove-accounts`. *Note* All gitlab processes need to be stopped before running the command.

To remove all omnibus-gitlab data use `sudo gitlab-ctl cleanse`.

140
To uninstall omnibus-gitlab, preserving your data (repositories, database, configuration), run the following commands.
141
142

```
143
# Stop gitlab and remove its supervision process
144
145
146
147
sudo systemctl stop    gitlab-runsvdir
sudo systemctl disable gitlab-runsvdir
sudo rm /usr/lib/systemd/system/gitlab-runsvdir.service
sudo systemctl daemon-reload
148
sudo gitlab-ctl uninstall
149

150
151
# (Replace with gitlab-ce if you have GitLab FOSS installed)

152
# Debian/Ubuntu
153
sudo apt remove gitlab-ee
154

155
# Redhat/Centos
156
sudo yum remove gitlab-ee
157
```
158

159
### Common installation problems
160

161
This section has been moved to the separate document [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md).
162

163
Section below remains for historical reasons(mainly to not break existing links). Each section contains the link to the new location.
164

Marcel Amirault's avatar
Marcel Amirault committed
165
#### Apt error 'The requested URL returned error: 403'
166

167
See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#apt-error-the-requested-url-returned-error-403).
168

Marcel Amirault's avatar
Marcel Amirault committed
169
#### GitLab is unreachable in my browser
170

171
See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#gitlab-is-unreachable-in-my-browser).
172

Marcel Amirault's avatar
Marcel Amirault committed
173
#### Emails are not being delivered
174

175
See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#emails-are-not-being-delivered).
176

Marcel Amirault's avatar
Marcel Amirault committed
177
#### Reconfigure freezes at `ruby_block[supervise_redis_sleep] action run`
178

179
See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#reconfigure-freezes-at-ruby_blocksupervise_redis_sleep-action-run).
180

Marcel Amirault's avatar
Marcel Amirault committed
181
#### TCP ports for GitLab services are already taken
182

183
See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#tcp-ports-for-gitlab-services-are-already-taken).
184

Marcel Amirault's avatar
Marcel Amirault committed
185
#### Git SSH access stops working on SELinux-enabled systems
186

187
See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#git-ssh-access-stops-working-on-selinux-enabled-systems
188
).
Marin Jankovski's avatar
Marin Jankovski committed
189

Marcel Amirault's avatar
Marcel Amirault committed
190
#### Postgres error 'FATAL:  could not create shared memory segment: Cannot allocate memory'
191

192
See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#postgres-error-fatal-could-not-create-shared-memory-segment-cannot-allocate-memory).
193

Marcel Amirault's avatar
Marcel Amirault committed
194
#### Reconfigure complains about the GLIBC version
195

196
See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#reconfigure-complains-about-the-glibc-version).
197

Marcel Amirault's avatar
Marcel Amirault committed
198
#### Reconfigure fails to create the git user
199

200
See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#reconfigure-fails-to-create-the-git-user).
201

Marcel Amirault's avatar
Marcel Amirault committed
202
#### Failed to modify kernel parameters with sysctl
203

204
See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#failed-to-modify-kernel-parameters-with-sysctl).
205

Marcel Amirault's avatar
Marcel Amirault committed
206
#### I am unable to install omnibus-gitlab without root access
207

208
See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#i-am-unable-to-install-omnibus-gitlab-without-root-access).
209

Marcel Amirault's avatar
Marcel Amirault committed
210
#### gitlab-rake assets:precompile fails with 'Permission denied'
211

212
See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#gitlab-rake-assetsprecompile-fails-with-permission-denied).
213

Marcel Amirault's avatar
Marcel Amirault committed
214
#### 'Short read or OOM loading DB' error
215

216
See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#short-read-or-oom-loading-db-error).
217

218
### Backups
219

220
See [doc/settings/backups.md](doc/settings/backups.md).
221

Marcel Amirault's avatar
Marcel Amirault committed
222
#### Backup and restore omnibus-gitlab configuration
223

224
See [doc/settings/backups.md](doc/settings/backups.md#backup-and-restore-omnibus-gitlab-configuration).
225

Marcel Amirault's avatar
Marcel Amirault committed
226
#### Creating an application backup
227

228
See [doc/settings/backups.md](doc/settings/backups.md#creating-an-application-backup).
229

230
### Restoring an application backup
231

232
See [backup restore documentation](https://docs.gitlab.com/ee/raketasks/backup_restore.html#omnibus-installations).
233

234
### Backup and restore using non-packaged database
235

Marin Jankovski's avatar
Marin Jankovski committed
236
If you are using non-packaged database see [documentation on using non-packaged database](doc/settings/database.md#using-a-non-packaged-postgresql-database-management-server).
237

238
239
### Upload backups to remote (cloud) storage

240
For details check [backup restore document of GitLab CE](https://gitlab.com/gitlab-org/gitlab-foss/blob/966f68b33e1f15f08e383ec68346ed1bd690b59b/doc/raketasks/backup_restore.md#upload-backups-to-remote-cloud-storage).
241

242
## Invoking Rake tasks
243

244
See [doc/maintenance/README.md](doc/maintenance/README.md#invoking-rake-tasks).
245

246
## Directory structure
247
248
249
250
251

Omnibus-gitlab uses four different directories.

- `/opt/gitlab` holds application code for GitLab and its dependencies.
- `/var/opt/gitlab` holds application data and configuration files that
Jacob Vosmaer's avatar
Jacob Vosmaer committed
252
  `gitlab-ctl reconfigure` writes to.
253
254
255
256
257
- `/etc/gitlab` holds configuration files for omnibus-gitlab. These are
  the only files that you should ever have to edit manually.
- `/var/log/gitlab` contains all log data generated by components of
  omnibus-gitlab.

258
259
260
261
## Omnibus-gitlab and SELinux

Although omnibus-gitlab runs on systems that have SELinux enabled, it does not
use SELinux confinement features:
Marcel Amirault's avatar
Marcel Amirault committed
262

263
264
265
266
267
268
269
- omnibus-gitlab creates unconfined system users;
- omnibus-gitlab services run in an unconfined context.

The correct operation of Git access via SSH depends on the labeling of
`/var/opt/gitlab/.ssh`. If needed you can restore this labeling by running
`sudo gitlab-ctl reconfigure`.

270
271
272
273
Depending on your platform, `gitlab-ctl reconfigure` will install SELinux
modules required to make GitLab work. These modules are listed in
[files/gitlab-selinux/README.md](files/gitlab-selinux/README.md).

274
275
276
277
NSA, if you're reading this, we'd really appreciate it if you could contribute
back a SELinux profile for omnibus-gitlab :)
Of course, if anyone else is reading this, you're welcome to contribute the
SELinux profile too.
Sytse Sijbrandij's avatar
Sytse Sijbrandij committed
278

279
### Logs
280

281
This section has been moved to separate document [doc/settings/logs.md](doc/settings/logs.md).
282

Marcel Amirault's avatar
Marcel Amirault committed
283
#### Tail logs in a console on the server
284

285
See [doc/settings/logs.md](doc/settings/logs.md#tail-logs-in-a-console-on-the-server).
286

287
##### Runit logs
288

289
See [doc/settings/logs.md](doc/settings/logs.md#runit-logs).
290

291
##### Logrotate
292

293
See [doc/settings/logs.md](doc/settings/logs.md#logrotate).
Jacob Vosmaer's avatar
Jacob Vosmaer committed
294

295
##### UDP log shipping (GitLab Enterprise Edition only)
296

297
See [doc/settings/logs.md](doc/settings/logs.md#udp-log-shipping-gitlab-enterprise-edition-only)
298

299
300
### Create a user and database for GitLab

301
See [doc/settings/database.md](doc/settings/database.md).
302

303
### Configure omnibus-gitlab to connect to it
304

305
See [doc/settings/database.md](doc/settings/database.md).
306
307
308

### Seed the database (fresh installs only)

309
See [doc/settings/database.md](doc/settings/database.md).
310

311
## Building your own package
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
312

313
See [the separate build documentation](doc/build/README.md).
314

315
316
317
318
319
## Running a custom GitLab version

It is not recommended to make changes to any of the files in `/opt/gitlab`
after installing omnibus-gitlab: they will either conflict with or be
overwritten by future updates. If you want to run a custom version of GitLab
320
you can [build your own package](doc/build/README.md) or use [another installation
321
322
method][CE README].

323
324
325
326
327
## Acknowledgments

This omnibus installer project is based on the awesome work done by Chef in
[omnibus-chef-server][omnibus-chef-server].

328
[downloads]: https://about.gitlab.com/downloads/
329
[CE README]: https://gitlab.com/gitlab-org/gitlab-foss/blob/master/README.md
330
[omnibus-chef-server]: https://github.com/opscode/omnibus-chef-server
331
[database.yml.mysql]: https://gitlab.com/gitlab-org/gitlab-foss/blob/master/config/database.yml.mysql
332
[svlogd]: http://smarden.org/runit/svlogd.8.html
Marcel Amirault's avatar
Marcel Amirault committed
333
[installation]: https://about.gitlab.com/install/
334
[gitlab.rb.template]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template