2014-06-26 08:11:09 +00:00
# Omnibus GitLab
2013-11-21 11:06:42 +00:00
2015-12-23 20:02:02 +00:00
## Description
2014-02-28 14:55:43 +00:00
This project creates full-stack platform-specific [downloadable packages for GitLab][downloads].
For other installation options please see the
2014-06-26 08:11:09 +00:00
[GitLab installation page][installation].
2013-11-21 11:06:42 +00:00
2014-08-05 14:49:49 +00:00
## 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.
2015-07-20 12:13:24 +00:00
## Documentation
2014-04-22 09:14:16 +00:00
2023-12-08 12:11:20 +00:00
The documentation can be found in the [doc directory ](doc/index.md ).
2014-04-22 09:14:16 +00:00
2015-05-26 12:36:09 +00:00
## Omnibus fork
2018-03-27 16:07:21 +00:00
Omnibus GitLab is using a fork of [omnibus project ](https://github.com/chef/omnibus ). For additional information see the comments in the [Gemfile ](/Gemfile ).
2015-05-26 12:36:09 +00:00
2019-07-08 01:35:34 +00:00
## Deprecated links
2014-10-23 09:47:35 +00:00
2023-12-08 12:11:20 +00:00
*We left the links below in the readme to preserve old links, but please use the [doc directory ](doc/index.md ) to browse the complete documentation.*
2014-10-23 09:47:35 +00:00
2017-09-01 08:48:55 +00:00
## Contributing
Please see the [contribution guidelines ](CONTRIBUTING.md )
2015-07-16 15:40:42 +00:00
## Installation
Please follow the steps on the [downloads page][downloads].
### After installation
2019-10-31 13:34:06 +00:00
Your GitLab instance should be reachable over HTTP at the IP or hostname of your
2015-11-14 09:28:51 +00:00
server. You can login as an admin user with username `root` and password `5iveL!fe` .
2015-07-16 15:40:42 +00:00
2023-12-08 12:11:20 +00:00
See [doc/maintenance/index.md ](doc/maintenance/index.md ) for useful commands
2015-11-14 09:28:51 +00:00
to control/debug your GitLab instance.
2015-07-16 15:40:42 +00:00
2015-07-14 11:55:42 +00:00
### Configuration options
2014-12-09 07:18:25 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/configuration.md ](doc/settings/configuration.md ).
2014-12-09 07:18:25 +00:00
2019-07-08 01:35:34 +00:00
#### Configuring the external URL for GitLab
2014-02-13 18:20:47 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/configuration.md ](doc/settings/configuration.md#configuring-the-external-url-for-gitlab ).
2014-02-14 16:58:08 +00:00
2019-07-08 01:35:34 +00:00
#### Storing Git data in an alternative directory
2014-04-04 11:34:14 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/configuration.md ](doc/settings/configuration.md#storing-git-data-in-an-alternative-directory ).
2014-04-10 08:26:35 +00:00
2019-07-08 01:35:34 +00:00
#### Changing the name of the Git user / group
2014-04-10 08:26:35 +00:00
2023-01-07 20:19:30 +00:00
See [doc/settings/configuration.md ](doc/settings/configuration.md#change-the-name-of-the-git-user-or-group ).
2014-09-23 09:00:55 +00:00
2019-07-08 01:35:34 +00:00
#### Setting up LDAP sign-in
2014-09-23 09:00:55 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/ldap.md ](doc/settings/ldap.md ).
2014-04-04 11:34:14 +00:00
2019-07-08 01:35:34 +00:00
#### Enable HTTPS
2014-05-01 13:24:50 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/nginx.md ](doc/settings/nginx.md#enable-https ).
2015-07-13 15:37:05 +00:00
2019-07-08 01:35:34 +00:00
#### Redirect `HTTP` requests to `HTTPS`
2015-06-01 15:28:02 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/nginx.md ](doc/settings/nginx.md#redirect-http-requests-to-https ).
2015-06-01 15:28:02 +00:00
2019-07-08 01:35:34 +00:00
#### Change the default port and the ssl certificate locations
2014-06-03 15:43:28 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/nginx.md ](doc/settings/nginx.md#change-the-default-port-and-the-ssl-certificate-locations ).
2014-06-03 15:43:28 +00:00
2019-07-08 01:35:34 +00:00
#### Use non-packaged web-server
2015-07-08 09:20:51 +00:00
2015-07-14 11:35:15 +00:00
For using an existing Nginx, Passenger, or Apache webserver see [doc/settings/nginx.md ](doc/settings/nginx.md#using-a-non-bundled-web-server ).
2015-07-08 09:20:51 +00:00
2019-07-08 01:35:34 +00:00
#### Using a non-packaged PostgreSQL database management server
2014-08-06 09:59:00 +00:00
2019-06-27 11:53:11 +00:00
To connect to an external PostgreSQL DBMS see [doc/settings/database.md ](doc/settings/database.md )
2014-08-06 09:59:00 +00:00
2019-07-08 01:35:34 +00:00
#### Using a non-packaged Redis instance
2014-05-01 13:24:50 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/redis.md ](doc/settings/redis.md ).
2014-09-02 10:09:49 +00:00
2019-07-08 01:35:34 +00:00
#### Adding ENV Vars to the Gitlab Runtime Environment
2014-05-21 16:11:02 +00:00
2015-07-14 11:35:15 +00:00
See
[doc/settings/environment-variables.md ](doc/settings/environment-variables.md ).
2014-05-21 16:11:02 +00:00
2019-07-08 01:35:34 +00:00
#### Changing gitlab.yml settings
2014-07-29 09:22:55 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/gitlab.yml.md ](doc/settings/gitlab.yml.md ).
2014-07-29 09:22:55 +00:00
2019-07-08 01:35:34 +00:00
#### Specify numeric user and group identifiers
2014-09-02 10:17:31 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/configuration.md ](doc/settings/configuration.md#specify-numeric-user-and-group-identifiers ).
2014-09-02 10:17:31 +00:00
2019-07-08 01:35:34 +00:00
#### Sending application email via SMTP
2014-09-08 12:56:12 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/smtp.md ](doc/settings/smtp.md ).
2014-09-08 12:56:12 +00:00
2019-07-08 01:35:34 +00:00
#### Omniauth (Google, Twitter, GitHub login)
2014-07-14 16:15:15 +00:00
2015-07-14 11:35:15 +00:00
Omniauth configuration is documented in
2019-11-01 10:52:15 +00:00
[docs.gitlab.com ](https://docs.gitlab.com/ee/integration/omniauth.html ).
2014-12-19 13:16:03 +00:00
2019-07-08 01:35:34 +00:00
#### Adjusting Unicorn settings
2014-12-19 13:16:03 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/unicorn.md ](doc/settings/unicorn.md ).
2014-12-19 13:16:03 +00:00
2019-07-08 01:35:34 +00:00
#### Setting the NGINX listen address or addresses
2015-04-03 11:45:15 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/nginx.md ](doc/settings/nginx.md ).
2015-04-03 11:45:15 +00:00
2019-07-08 01:35:34 +00:00
#### Inserting custom NGINX settings into the GitLab server block
2015-04-03 12:27:58 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/nginx.md ](doc/settings/nginx.md ).
2015-07-13 13:56:59 +00:00
2019-07-08 01:35:34 +00:00
#### Inserting custom settings into the NGINX config
2015-07-13 13:56:59 +00:00
2015-07-14 11:35:15 +00:00
See [doc/settings/nginx.md ](doc/settings/nginx.md ).
2015-04-03 12:27:58 +00:00
2019-07-08 01:35:34 +00:00
#### Only start omnibus-gitlab services after a given filesystem is mounted
2015-07-14 11:55:42 +00:00
See [doc/settings/configuration.md ](doc/settings/configuration.md#only-start-omnibus-gitlab-services-after-a-given-filesystem-is-mounted ).
2015-07-14 11:35:15 +00:00
### Updating
2014-04-04 13:13:12 +00:00
2015-11-14 09:28:51 +00:00
Instructions for updating your Omnibus installation and upgrading from a manual
2023-12-08 12:11:20 +00:00
installation are in the [update directory ](doc/update/ ).
2014-07-25 08:46:44 +00:00
2023-01-04 14:17:54 +00:00
### Uninstalling Omnibus GitLab
2014-07-25 08:46:44 +00:00
2023-01-04 14:17:54 +00:00
See [doc/installation/index.md ](doc/installation/index.md#uninstall-the-linux-package-omnibus ).
2014-02-16 18:23:09 +00:00
2015-07-14 11:35:15 +00:00
### Common installation problems
2014-04-04 13:09:35 +00:00
2023-12-08 12:11:20 +00:00
This section has been moved to the separate document [doc/troubleshooting.md ](doc/troubleshooting.md ).
2014-04-04 13:09:35 +00:00
2015-07-14 11:35:15 +00:00
Section below remains for historical reasons(mainly to not break existing links). Each section contains the link to the new location.
2014-04-04 13:09:35 +00:00
2019-07-08 01:35:34 +00:00
#### Apt error 'The requested URL returned error: 403'
2015-06-22 09:02:48 +00:00
2023-12-08 12:11:20 +00:00
See [doc/troubleshooting.md ](doc/troubleshooting.md#apt-error-the-requested-url-returned-error-403 ).
2014-04-04 13:09:35 +00:00
2019-07-08 01:35:34 +00:00
#### GitLab is unreachable in my browser
2014-08-21 15:55:52 +00:00
2023-12-08 12:11:20 +00:00
See [doc/troubleshooting.md ](doc/troubleshooting.md#gitlab-is-unreachable-in-my-browser ).
2014-08-21 15:55:52 +00:00
2019-07-08 01:35:34 +00:00
#### Emails are not being delivered
2014-08-21 15:55:52 +00:00
2023-12-08 12:11:20 +00:00
See [doc/troubleshooting.md ](doc/troubleshooting.md#emails-are-not-being-delivered ).
2014-05-23 16:12:42 +00:00
2019-07-08 01:35:34 +00:00
#### TCP ports for GitLab services are already taken
2014-05-23 16:12:42 +00:00
2023-12-08 12:11:20 +00:00
See [doc/troubleshooting.md ](doc/troubleshooting.md#tcp-ports-for-gitlab-services-are-already-taken ).
2014-05-23 16:12:42 +00:00
2019-07-08 01:35:34 +00:00
#### Git SSH access stops working on SELinux-enabled systems
2014-04-04 13:09:35 +00:00
2023-12-08 12:11:20 +00:00
See [doc/troubleshooting.md ](doc/troubleshooting.md#selinux-enabled-systems ).
2014-10-16 10:29:48 +00:00
2019-07-08 01:35:34 +00:00
#### Postgres error 'FATAL: could not create shared memory segment: Cannot allocate memory'
2014-04-04 13:09:35 +00:00
2023-12-08 12:11:20 +00:00
See [doc/troubleshooting.md ](doc/troubleshooting.md#postgresql-error-fatal-could-not-create-shared-memory-segment-cannot-allocate-memory ).
2014-07-18 14:55:50 +00:00
2019-07-08 01:35:34 +00:00
#### Reconfigure complains about the GLIBC version
2014-07-18 14:55:50 +00:00
2023-12-08 12:11:20 +00:00
See [doc/troubleshooting.md ](doc/troubleshooting.md#reconfigure-complains-about-the-glibc-version ).
2014-04-04 13:09:35 +00:00
2019-07-08 01:35:34 +00:00
#### Reconfigure fails to create the git user
2014-07-18 14:55:50 +00:00
2023-12-08 12:11:20 +00:00
See [doc/troubleshooting.md ](doc/troubleshooting.md#reconfigure-fails-to-create-the-git-user ).
2014-04-04 13:09:35 +00:00
2019-07-08 01:35:34 +00:00
#### Failed to modify kernel parameters with sysctl
2014-08-28 10:03:37 +00:00
2023-12-08 12:11:20 +00:00
See [doc/troubleshooting.md ](doc/troubleshooting.md#failed-to-modify-kernel-parameters-with-sysctl ).
2015-06-16 08:25:02 +00:00
2019-07-08 01:35:34 +00:00
#### I am unable to install omnibus-gitlab without root access
2015-06-16 08:25:02 +00:00
2023-12-08 12:11:20 +00:00
See [doc/troubleshooting.md ](doc/troubleshooting.md#i-am-unable-to-install-omnibus-gitlab-without-root-access ).
2015-06-16 08:25:02 +00:00
2019-07-08 01:35:34 +00:00
#### gitlab-rake assets:precompile fails with 'Permission denied'
2015-06-16 08:25:02 +00:00
2023-12-08 12:11:20 +00:00
See [doc/troubleshooting.md ](doc/troubleshooting.md#gitlab-rake-assetsprecompile-fails-with-permission-denied ).
2014-08-28 10:03:37 +00:00
2019-07-08 01:35:34 +00:00
#### 'Short read or OOM loading DB' error
2014-07-25 22:41:13 +00:00
2023-12-08 12:11:20 +00:00
See [doc/troubleshooting.md ](doc/troubleshooting.md#short-read-or-oom-loading-db-error ).
2014-07-25 22:41:13 +00:00
2015-07-14 11:55:42 +00:00
### Backups
2014-05-05 13:19:58 +00:00
2015-07-14 11:55:42 +00:00
See [doc/settings/backups.md ](doc/settings/backups.md ).
2014-05-23 16:18:05 +00:00
2019-07-08 01:35:34 +00:00
#### Backup and restore omnibus-gitlab configuration
2014-05-23 16:18:05 +00:00
2015-07-14 11:55:42 +00:00
See [doc/settings/backups.md ](doc/settings/backups.md#backup-and-restore-omnibus-gitlab-configuration ).
2014-05-23 16:18:05 +00:00
2019-07-08 01:35:34 +00:00
#### Creating an application backup
2014-08-15 10:07:04 +00:00
2015-07-14 11:55:42 +00:00
See [doc/settings/backups.md ](doc/settings/backups.md#creating-an-application-backup ).
2014-09-19 08:42:31 +00:00
2015-07-14 11:55:42 +00:00
### Restoring an application backup
2014-11-27 15:54:26 +00:00
2023-10-16 23:58:05 +00:00
See [restore documentation ](https://docs.gitlab.com/ee/administration/backup_restore/restore_gitlab.html#restore-for-linux-package-installations ).
2014-11-27 15:54:26 +00:00
2015-07-14 11:55:42 +00:00
### Backup and restore using non-packaged database
2014-04-04 13:13:12 +00:00
2015-06-25 15:21:14 +00:00
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 ).
2015-06-11 14:43:15 +00:00
2014-10-17 12:11:07 +00:00
### Upload backups to remote (cloud) storage
2023-10-16 23:58:05 +00:00
For details check [backup documentation ](https://docs.gitlab.com/ee/administration/backup_restore/backup_gitlab.html#upload-backups-to-a-remote-cloud-storage ).
2014-10-17 12:11:07 +00:00
2014-04-04 13:13:12 +00:00
## Invoking Rake tasks
2014-02-16 18:23:09 +00:00
2021-10-17 23:38:23 +00:00
See [doc/maintenance/index.md ](doc/maintenance/index.md#invoking-rake-tasks ).
2014-02-13 13:57:16 +00:00
2014-04-04 13:13:12 +00:00
## Directory structure
2014-02-13 13:57:16 +00:00
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
2014-02-14 16:58:33 +00:00
`gitlab-ctl reconfigure` writes to.
2014-02-13 13:57:16 +00:00
- `/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.
2014-07-29 09:22:55 +00:00
## Omnibus-gitlab and SELinux
Although omnibus-gitlab runs on systems that have SELinux enabled, it does not
use SELinux confinement features:
2019-07-08 01:35:34 +00:00
2014-07-29 09:22:55 +00:00
- 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` .
2014-08-26 09:38:45 +00:00
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 ).
2015-11-14 09:28:51 +00:00
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.
2014-10-15 17:05:30 +00:00
2015-07-14 10:47:12 +00:00
### Logs
2014-06-17 07:41:06 +00:00
2015-07-14 10:47:12 +00:00
This section has been moved to separate document [doc/settings/logs.md ](doc/settings/logs.md ).
2014-06-17 07:41:06 +00:00
2019-07-08 01:35:34 +00:00
#### Tail logs in a console on the server
2014-06-17 07:41:06 +00:00
2015-07-14 10:47:12 +00:00
See [doc/settings/logs.md ](doc/settings/logs.md#tail-logs-in-a-console-on-the-server ).
2014-06-17 07:41:06 +00:00
2015-07-14 10:47:12 +00:00
##### Runit logs
2014-06-17 07:41:06 +00:00
2015-07-14 10:47:12 +00:00
See [doc/settings/logs.md ](doc/settings/logs.md#runit-logs ).
2014-06-17 07:41:06 +00:00
2015-07-14 10:47:12 +00:00
##### Logrotate
2014-06-17 07:41:06 +00:00
2015-07-14 10:47:12 +00:00
See [doc/settings/logs.md ](doc/settings/logs.md#logrotate ).
2014-06-26 15:10:19 +00:00
2015-07-14 10:47:12 +00:00
##### UDP log shipping (GitLab Enterprise Edition only)
2014-10-08 16:21:31 +00:00
2015-07-14 10:47:12 +00:00
See [doc/settings/logs.md ](doc/settings/logs.md#udp-log-shipping-gitlab-enterprise-edition-only )
2014-06-26 13:38:05 +00:00
2014-04-11 10:03:17 +00:00
### Create a user and database for GitLab
2014-11-04 11:17:08 +00:00
See [doc/settings/database.md ](doc/settings/database.md ).
2014-04-11 10:03:17 +00:00
2014-04-14 13:52:36 +00:00
### Configure omnibus-gitlab to connect to it
2014-04-11 10:03:17 +00:00
2014-11-04 11:17:08 +00:00
See [doc/settings/database.md ](doc/settings/database.md ).
2014-04-11 10:03:17 +00:00
### Seed the database (fresh installs only)
2014-11-04 11:17:08 +00:00
See [doc/settings/database.md ](doc/settings/database.md ).
2014-04-11 10:03:17 +00:00
2014-02-14 16:52:50 +00:00
## Building your own package
2013-11-21 11:06:42 +00:00
2021-10-17 23:38:23 +00:00
See [the separate build documentation ](doc/build/index.md ).
2014-02-17 13:19:41 +00:00
2014-04-28 07:55:26 +00:00
## 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
2021-10-17 23:38:23 +00:00
you can [build your own package ](doc/build/index.md ) or use [another installation
2014-04-28 07:55:26 +00:00
method][CE README].
2014-03-04 07:09:07 +00:00
## Acknowledgments
This omnibus installer project is based on the awesome work done by Chef in
[omnibus-chef-server][omnibus-chef-server].
2014-06-26 08:00:14 +00:00
[downloads]: https://about.gitlab.com/downloads/
2019-08-13 16:42:56 +00:00
[CE README]: https://gitlab.com/gitlab-org/gitlab-foss/blob/master/README.md
2014-03-04 07:09:07 +00:00
[omnibus-chef-server]: https://github.com/opscode/omnibus-chef-server
2019-08-13 16:42:56 +00:00
[database.yml.mysql]: https://gitlab.com/gitlab-org/gitlab-foss/blob/master/config/database.yml.mysql
2014-06-17 07:41:06 +00:00
[svlogd]: http://smarden.org/runit/svlogd.8.html
2019-07-08 01:35:34 +00:00
[installation]: https://about.gitlab.com/install/
2015-11-14 09:28:51 +00:00
[gitlab.rb.template]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template
