# Omnibus GitLab

## Description

This project creates full-stack platform-specific [downloadable packages for GitLab][downloads].
For other installation options please see the
[GitLab installation page][installation].

## 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.

## Documentation

The documentation can be found in the [doc directory](doc/index.md).

## Omnibus fork

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

## Deprecated links

*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.*

## Contributing

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

## Installation

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

### After installation

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

See [doc/maintenance/index.md](doc/maintenance/index.md) for useful commands
to control/debug your GitLab instance.

### Configuration options

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

#### Configuring the external URL for GitLab

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

#### Storing Git data in an alternative directory

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

#### Changing the name of the Git user / group

See [doc/settings/configuration.md](doc/settings/configuration.md#change-the-name-of-the-git-user-or-group).

#### Setting up LDAP sign-in

See [doc/settings/ldap.md](doc/settings/ldap.md).

#### Enable HTTPS

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

#### Redirect `HTTP` requests to `HTTPS`

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

#### Change the default port and the ssl certificate locations

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

#### Use non-packaged web-server

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

#### Using a non-packaged PostgreSQL database management server

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

#### Using a non-packaged Redis instance

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

#### Adding ENV Vars to the Gitlab Runtime Environment

See
[doc/settings/environment-variables.md](doc/settings/environment-variables.md).

#### Changing gitlab.yml settings

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

#### Specify numeric user and group identifiers

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

#### Sending application email via SMTP

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

#### Omniauth (Google, Twitter, GitHub login)

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

#### Adjusting Unicorn settings

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

#### Setting the NGINX listen address or addresses

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

#### Inserting custom NGINX settings into the GitLab server block

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

#### Inserting custom settings into the NGINX config

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

#### Only start omnibus-gitlab services after a given filesystem is mounted

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

### Updating

Instructions for updating your Omnibus installation and upgrading from a manual
installation are in the [update directory](doc/update/).

### Uninstalling Omnibus GitLab

See [doc/installation/index.md](doc/installation/index.md#uninstall-the-linux-package-omnibus).

### Common installation problems

This section has been moved to the separate document [doc/troubleshooting.md](doc/troubleshooting.md).

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

#### Apt error 'The requested URL returned error: 403'

See [doc/troubleshooting.md](doc/troubleshooting.md#apt-error-the-requested-url-returned-error-403).

#### GitLab is unreachable in my browser

See [doc/troubleshooting.md](doc/troubleshooting.md#gitlab-is-unreachable-in-my-browser).

#### Emails are not being delivered

See [doc/troubleshooting.md](doc/troubleshooting.md#emails-are-not-being-delivered).

#### TCP ports for GitLab services are already taken

See [doc/troubleshooting.md](doc/troubleshooting.md#tcp-ports-for-gitlab-services-are-already-taken).

#### Git SSH access stops working on SELinux-enabled systems

See [doc/troubleshooting.md](doc/troubleshooting.md#selinux-enabled-systems).

#### Postgres error 'FATAL:  could not create shared memory segment: Cannot allocate memory'

See [doc/troubleshooting.md](doc/troubleshooting.md#postgresql-error-fatal-could-not-create-shared-memory-segment-cannot-allocate-memory).

#### Reconfigure complains about the GLIBC version

See [doc/troubleshooting.md](doc/troubleshooting.md#reconfigure-complains-about-the-glibc-version).

#### Reconfigure fails to create the git user

See [doc/troubleshooting.md](doc/troubleshooting.md#reconfigure-fails-to-create-the-git-user).

#### Failed to modify kernel parameters with sysctl

See [doc/troubleshooting.md](doc/troubleshooting.md#failed-to-modify-kernel-parameters-with-sysctl).

#### I am unable to install omnibus-gitlab without root access

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

#### gitlab-rake assets:precompile fails with 'Permission denied'

See [doc/troubleshooting.md](doc/troubleshooting.md#gitlab-rake-assetsprecompile-fails-with-permission-denied).

#### 'Short read or OOM loading DB' error

See [doc/troubleshooting.md](doc/troubleshooting.md#short-read-or-oom-loading-db-error).

### Backups

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

#### Backup and restore omnibus-gitlab configuration

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

#### Creating an application backup

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

### Restoring an application backup

See [restore documentation](https://docs.gitlab.com/ee/administration/backup_restore/restore_gitlab.html#restore-for-linux-package-installations).

### Backup and restore using non-packaged database

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).

### Upload backups to remote (cloud) storage

For details check [backup documentation](https://docs.gitlab.com/ee/administration/backup_restore/backup_gitlab.html#upload-backups-to-a-remote-cloud-storage).

## Invoking Rake tasks

See [doc/maintenance/index.md](doc/maintenance/index.md#invoking-rake-tasks).

## Directory structure

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
  `gitlab-ctl reconfigure` writes to.
- `/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.

## Omnibus-gitlab and SELinux

Although omnibus-gitlab runs on systems that have SELinux enabled, it does not
use SELinux confinement features:

- 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`.

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).

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.

### Logs

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

#### Tail logs in a console on the server

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

##### Runit logs

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

##### Logrotate

See [doc/settings/logs.md](doc/settings/logs.md#logrotate).

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

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

### Create a user and database for GitLab

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

### Configure omnibus-gitlab to connect to it

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

### Seed the database (fresh installs only)

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

## Building your own package

See [the separate build documentation](doc/build/index.md).

## 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
you can [build your own package](doc/build/index.md) or use [another installation
method][CE README].

## Acknowledgments

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

[downloads]: https://about.gitlab.com/downloads/
[CE README]: https://gitlab.com/gitlab-org/gitlab-foss/blob/master/README.md
[omnibus-chef-server]: https://github.com/opscode/omnibus-chef-server
[database.yml.mysql]: https://gitlab.com/gitlab-org/gitlab-foss/blob/master/config/database.yml.mysql
[svlogd]: http://smarden.org/runit/svlogd.8.html
[installation]: https://about.gitlab.com/install/
[gitlab.rb.template]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template