diff --git a/README.md b/README.md index ac98eb1aedc338a11248dd9814f7f0bef04aea85_UkVBRE1FLm1k..4f132b62117b5755fb78c572d87284b02c1546b0_UkVBRE1FLm1k 100644 --- a/README.md +++ b/README.md @@ -29,10 +29,85 @@ ## Configuration options -GitLab and GitLab CI are configured by setting their relevant options in -`/etc/gitlab/gitlab.rb`. For a complete list of available options, visit the -[gitlab.rb.template][]. New installations starting from GitLab 7.6, will have -all the options of the template listed in `/etc/gitlab/gitlab.rb` by default. +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#changing-the-name-of-the-git-user-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 or MySQL DBMS see [doc/settings/database.md](doc/settings/database.md) (MySQL support in the Omnibus Packages is Enterprise Only). + +##### 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 +[doc.gitlab.com](http://doc.gitlab.com/ce/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). ## Installation @@ -60,6 +135,69 @@ Your GitLab instance should 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`. +#### Starting and stopping + +After omnibus-gitlab is installed and configured, your server will have a Runit +service directory (`runsvdir`) process running that gets started at boot via +`/etc/inittab` or the `/etc/init/gitlab-runsvdir.conf` Upstart resource. You +should not have to deal with the `runsvdir` process directly; you can use the +`gitlab-ctl` front-end instead. + +You can start, stop or restart GitLab and all of its components with the +following commands. + +```shell +# Start all GitLab components +sudo gitlab-ctl start + +# Stop all GitLab components +sudo gitlab-ctl stop + +# Restart all GitLab components +sudo gitlab-ctl restart +``` + +Note that on a single-core server it may take up to a minute to restart Unicorn +and Sidekiq. Your GitLab instance will give a 502 error until Unicorn is up +again. + +It is also possible to start, stop or restart individual components. + +```shell +sudo gitlab-ctl restart sidekiq +``` + +Unicorn supports zero-downtime reloads. These can be triggered as follows: + +```shell +sudo gitlab-ctl hup unicorn +``` + +Note that you cannot use a Unicorn reload to update the Ruby runtime. + +### Updating + +Instructions for updating your Omnibus installation and upgrading from a manual installation are in the [update doc](doc/update.md). + +### Uninstalling omnibus-gitlab + +To uninstall omnibus-gitlab, preserving your data (repositories, database, configuration), run the following commands. + +``` +# Stop gitlab and remove its supervision process +sudo gitlab-ctl uninstall + +# Debian/Ubuntu +sudo dpkg -r gitlab + +# Redhat/Centos +sudo rpm -e gitlab +``` + +To remove all omnibus-gitlab data use `sudo gitlab-ctl cleanse`. + +To remove all users and groups created by omnibus-gitlab, before removing the gitlab package (with dpkg or yum) run `sudo gitlab-ctl remove_users`. *Note* All gitlab processes need to be stopped before runnign the command. + ### Common installation problems This section has been moved to the separate document [doc/common_installation_problems.md](doc/common_installation_problems.md). @@ -123,68 +261,6 @@ See [doc/common_installation_problems.md](doc/common_installation_problems.mdr#short-read-or-oom-loading-db-error). -### Uninstalling omnibus-gitlab - -To uninstall omnibus-gitlab, preserving your data (repositories, database, configuration), run the following commands. - -``` -# Stop gitlab and remove its supervision process -sudo gitlab-ctl uninstall - -# Debian/Ubuntu -sudo dpkg -r gitlab - -# Redhat/Centos -sudo rpm -e gitlab -``` - -To remove all omnibus-gitlab data use `sudo gitlab-ctl cleanse`. - -To remove all users and groups created by omnibus-gitlab, before removing the gitlab package (with dpkg or yum) run `sudo gitlab-ctl remove_users`. *Note* All gitlab processes need to be stopped before runnign the command. - -## Updating - -Instructions for updating your Omnibus installation and upgrading from a manual installation are in the [update doc](doc/update.md). - -## Starting and stopping - -After omnibus-gitlab is installed and configured, your server will have a Runit -service directory (`runsvdir`) process running that gets started at boot via -`/etc/inittab` or the `/etc/init/gitlab-runsvdir.conf` Upstart resource. You -should not have to deal with the `runsvdir` process directly; you can use the -`gitlab-ctl` front-end instead. - -You can start, stop or restart GitLab and all of its components with the -following commands. - -```shell -# Start all GitLab components -sudo gitlab-ctl start - -# Stop all GitLab components -sudo gitlab-ctl stop - -# Restart all GitLab components -sudo gitlab-ctl restart -``` - -Note that on a single-core server it may take up to a minute to restart Unicorn -and Sidekiq. Your GitLab instance will give a 502 error until Unicorn is up -again. - -It is also possible to start, stop or restart individual components. - -```shell -sudo gitlab-ctl restart sidekiq -``` - -Unicorn supports zero-downtime reloads. These can be triggered as follows: - -```shell -sudo gitlab-ctl hup unicorn -``` - -Note that you cannot use a Unicorn reload to update the Ruby runtime. ## Configuration @@ -214,5 +290,4 @@ NOTE: Your machines SSH host keys are stored in a separate location at `/etc/ssh/`. Be sure to also [backup and restore those keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079) to avoid man-in-the-middle attack warnings if you have to perform a full machine restore. -### Configuring the external URL for GitLab @@ -218,150 +293,4 @@ -In order for GitLab to display correct repository clone links to your users -it needs to know the URL under which it is reached by your users, e.g. -`http://gitlab.example.com`. Add or edit the following line in -`/etc/gitlab/gitlab.rb`: - -```ruby -external_url "http://gitlab.example.com" -``` - -Run `sudo gitlab-ctl reconfigure` for the change to take effect. - - -### Storing Git data in an alternative directory - -By default, omnibus-gitlab stores Git repository data under -`/var/opt/gitlab/git-data`: repositories are stored in -`/var/opt/gitlab/git-data/repositories`, and satellites in -`/var/opt/gitlab/git-data/gitlab-satellites`. You can change the location of -the `git-data` parent directory by adding the following line to -`/etc/gitlab/gitlab.rb`. - -```ruby -git_data_dir "/mnt/nas/git-data" -``` - -Note that the target directory and any of its subpaths must not be a symlink. - -Run `sudo gitlab-ctl reconfigure` for the change to take effect. - -If you already have existing Git repositories in `/var/opt/gitlab/git-data` you -can move them to the new location as follows: - -```shell -# Prevent users from writing to the repositories while you move them. -sudo gitlab-ctl stop - -# Only move 'repositories'; 'gitlab-satellites' will be recreated -# automatically. Note there is _no_ slash behind 'repositories', but there _is_ a -# slash behind 'git-data'. -sudo rsync -av /var/opt/gitlab/git-data/repositories /mnt/nas/git-data/ - -# Fix permissions if necessary -sudo gitlab-ctl reconfigure - -# Double-check directory layout in /mnt/nas/git-data. Expected output: -# gitlab-satellites repositories -sudo ls /mnt/nas/git-data/ - -# Done! Start GitLab and verify that you can browse through the repositories in -# the web interface. -sudo gitlab-ctl start -``` - -### Changing the name of the Git user / group - -By default, omnibus-gitlab uses the user name `git` for Git gitlab-shell login, -ownership of the Git data itself, and SSH URL generation on the web interface. -Similarly, `git` group is used for group ownership of the Git data. You can -change the user and group by adding the following lines to -`/etc/gitlab/gitlab.rb`. - -```ruby -user['username'] = "gitlab" -user['group'] = "gitlab" -``` - -Run `sudo gitlab-ctl reconfigure` for the change to take effect. - -### 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 or MySQL DBMS see [doc/settings/database.md](doc/settings/database.md) (MySQL support in the Omnibus Packages is Enterprise Only). - -## 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 - -Omnibus-gitlab creates users for GitLab, PostgreSQL, Redis and NGINX. You can -specify the numeric identifiers for these users in `/etc/gitlab/gitlab.rb` as -follows. - -```ruby -user['uid'] = 1234 -user['gid'] = 1234 -postgresql['uid'] = 1235 -postgresql['gid'] = 1235 -redis['uid'] = 1236 -redis['gid'] = 1236 -web_server['uid'] = 1237 -web_server['gid'] = 1237 -``` - -### Sending application email via SMTP - -See [doc/settings/smtp.md](doc/settings/smtp.md). - -### Omniauth (Google, Twitter, GitHub login) - -Omniauth configuration is documented in -[doc.gitlab.com](http://doc.gitlab.com/ce/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). ## Backups diff --git a/doc/README.md b/doc/README.md index ac98eb1aedc338a11248dd9814f7f0bef04aea85_ZG9jL1JFQURNRS5tZA==..4f132b62117b5755fb78c572d87284b02c1546b0_ZG9jL1JFQURNRS5tZA== 100644 --- a/doc/README.md +++ b/doc/README.md @@ -19,7 +19,7 @@ ## Configuring -- [Configuration options](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template) +- [Configuration options](settings/configuration.md) - [SMTP](settings/smtp.md) - [NGINX](settings/nginx.md) - [LDAP](settings/ldap.md) diff --git a/doc/settings/README.md b/doc/settings/README.md index ac98eb1aedc338a11248dd9814f7f0bef04aea85_ZG9jL3NldHRpbmdzL1JFQURNRS5tZA==..4f132b62117b5755fb78c572d87284b02c1546b0_ZG9jL3NldHRpbmdzL1JFQURNRS5tZA== 100644 --- a/doc/settings/README.md +++ b/doc/settings/README.md @@ -1,5 +1,6 @@ # Configuring omnibus settings +- [Configuration options](configuration.md) - [SMTP](smtp.md) - [NGINX](nginx.md) - [LDAP](ldap.md) diff --git a/doc/settings/configuration.md b/doc/settings/configuration.md new file mode 100644 index 0000000000000000000000000000000000000000..4f132b62117b5755fb78c572d87284b02c1546b0_ZG9jL3NldHRpbmdzL2NvbmZpZ3VyYXRpb24ubWQ= --- /dev/null +++ b/doc/settings/configuration.md @@ -0,0 +1,155 @@ +# Configuration options + +GitLab and GitLab CI are configured by setting their relevant options in +`/etc/gitlab/gitlab.rb`. For a complete list of available options, visit the +[gitlab.rb.template][]. New installations starting from GitLab 7.6, will have +all the options of the template listed in `/etc/gitlab/gitlab.rb` by default. + + +### Configuring the external URL for GitLab + +In order for GitLab to display correct repository clone links to your users +it needs to know the URL under which it is reached by your users, e.g. +`http://gitlab.example.com`. Add or edit the following line in +`/etc/gitlab/gitlab.rb`: + +```ruby +external_url "http://gitlab.example.com" +``` + +Run `sudo gitlab-ctl reconfigure` for the change to take effect. + +### Storing Git data in an alternative directory + +By default, omnibus-gitlab stores Git repository data under +`/var/opt/gitlab/git-data`: repositories are stored in +`/var/opt/gitlab/git-data/repositories`, and satellites in +`/var/opt/gitlab/git-data/gitlab-satellites`. You can change the location of +the `git-data` parent directory by adding the following line to +`/etc/gitlab/gitlab.rb`. + +```ruby +git_data_dir "/mnt/nas/git-data" +``` + +Note that the target directory and any of its subpaths must not be a symlink. + +Run `sudo gitlab-ctl reconfigure` for the change to take effect. + +If you already have existing Git repositories in `/var/opt/gitlab/git-data` you +can move them to the new location as follows: + +```shell +# Prevent users from writing to the repositories while you move them. +sudo gitlab-ctl stop + +# Only move 'repositories'; 'gitlab-satellites' will be recreated +# automatically. Note there is _no_ slash behind 'repositories', but there _is_ a +# slash behind 'git-data'. +sudo rsync -av /var/opt/gitlab/git-data/repositories /mnt/nas/git-data/ + +# Fix permissions if necessary +sudo gitlab-ctl reconfigure + +# Double-check directory layout in /mnt/nas/git-data. Expected output: +# gitlab-satellites repositories +sudo ls /mnt/nas/git-data/ + +# Done! Start GitLab and verify that you can browse through the repositories in +# the web interface. +sudo gitlab-ctl start +``` + +### Changing the name of the Git user / group + +By default, omnibus-gitlab uses the user name `git` for Git gitlab-shell login, +ownership of the Git data itself, and SSH URL generation on the web interface. +Similarly, `git` group is used for group ownership of the Git data. You can +change the user and group by adding the following lines to +`/etc/gitlab/gitlab.rb`. + +```ruby +user['username'] = "gitlab" +user['group'] = "gitlab" +``` + +Run `sudo gitlab-ctl reconfigure` for the change to take effect. + +### 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 or MySQL DBMS see [doc/settings/database.md](doc/settings/database.md) (MySQL support in the Omnibus Packages is Enterprise Only). + +## 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 + +Omnibus-gitlab creates users for GitLab, PostgreSQL, Redis and NGINX. You can +specify the numeric identifiers for these users in `/etc/gitlab/gitlab.rb` as +follows. + +```ruby +user['uid'] = 1234 +user['gid'] = 1234 +postgresql['uid'] = 1235 +postgresql['gid'] = 1235 +redis['uid'] = 1236 +redis['gid'] = 1236 +web_server['uid'] = 1237 +web_server['gid'] = 1237 +``` + +### Sending application email via SMTP + +See [doc/settings/smtp.md](doc/settings/smtp.md). + +### Omniauth (Google, Twitter, GitHub login) + +Omniauth configuration is documented in +[doc.gitlab.com](http://doc.gitlab.com/ce/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).