diff --git a/doc/settings/backups.md b/doc/settings/backups.md index 313ff511fd8085f7dca36db45831fde14b6fd5b1_ZG9jL3NldHRpbmdzL2JhY2t1cHMubWQ=..8924ff5428f98910c39d88578d948a610dd9c1f9_ZG9jL3NldHRpbmdzL2JhY2t1cHMubWQ= 100644 --- a/doc/settings/backups.md +++ b/doc/settings/backups.md @@ -36,7 +36,6 @@ ``` 15 04 * * 2-6 umask 0077; tar cfz /secret/gitlab/backups/$(date "+etc-gitlab-\%s.tgz") -C / etc/gitlab - ``` [cron is rather particular](http://www.pantz.org/software/cron/croninfo.html) @@ -132,5 +131,6 @@ ```ruby gitlab_rails['manage_backup_path'] = false ``` + *Warning* If you set this configuration option, it is up to you to create the directory specified in `gitlab_rails['backup_path']` and to set permissions which will allow user specified in `user['username']` to have correct access. Failing to do so will prevent GitLab from creating the backup archive. diff --git a/doc/settings/configuration.md b/doc/settings/configuration.md index 313ff511fd8085f7dca36db45831fde14b6fd5b1_ZG9jL3NldHRpbmdzL2NvbmZpZ3VyYXRpb24ubWQ=..8924ff5428f98910c39d88578d948a610dd9c1f9_ZG9jL3NldHRpbmdzL2NvbmZpZ3VyYXRpb24ubWQ= 100644 --- a/doc/settings/configuration.md +++ b/doc/settings/configuration.md @@ -57,6 +57,6 @@ Follow the steps below to enable relative URL in GitLab: -1. (Optional) If you run short on resources, you can temporarily free up some - memory by shutting down Unicorn and Sidekiq with the following command: +1. (Optional) If you run short on resources, you can temporarily free up some + memory by shutting down Unicorn and Sidekiq with the following command: @@ -62,6 +62,6 @@ - ```shell - sudo gitlab-ctl stop unicorn - sudo gitlab-ctl stop sidekiq - ``` + ```shell + sudo gitlab-ctl stop unicorn + sudo gitlab-ctl stop sidekiq + ``` @@ -67,3 +67,3 @@ -1. Set the `external_url` in `/etc/gitlab/gitlab.rb`: +1. Set the `external_url` in `/etc/gitlab/gitlab.rb`: @@ -69,5 +69,5 @@ - ```ruby - external_url "https://example.com/gitlab" - ``` + ```ruby + external_url "https://example.com/gitlab" + ``` @@ -73,4 +73,4 @@ - In this example, the relative URL under which GitLab will be served will be - `/gitlab`. Change it to your liking. + In this example, the relative URL under which GitLab will be served will be + `/gitlab`. Change it to your liking. @@ -76,3 +76,3 @@ -1. Reconfigure GitLab for the changes to take effect: +1. Reconfigure GitLab for the changes to take effect: @@ -78,5 +78,5 @@ - ```shell - sudo gitlab-ctl reconfigure - ``` + ```shell + sudo gitlab-ctl reconfigure + ``` @@ -82,3 +82,3 @@ -1. Restart the services so that Unicorn and Sidekiq picks up the changes +1. Restart the services so that Unicorn and Sidekiq picks up the changes @@ -84,7 +84,7 @@ - ```shell - sudo gitlab-ctl restart - ``` + ```shell + sudo gitlab-ctl restart + ``` If you stumble upon any issues, see the [troubleshooting section](#relative-url-troubleshooting). @@ -252,7 +252,6 @@ By default, omnibus-gitlab package expects that following users exist: - ```bash # GitLab user (required) git @@ -400,7 +399,6 @@ gitlab-ctl reconfigure ``` - If the runnit service is not stopped and the home directories are not manually moved for the user, GitLab will encounter an error while reconfiguring: @@ -467,8 +465,6 @@ | `/var/opt/gitlab/gitlab-ci/builds` | 0700 | git:root | Holds CI build logs | | `/var/opt/gitlab/.ssh` | 0700 | git:git | Holds authorized keys | - - ## Only start Omnibus-GitLab services after a given filesystem is mounted If you want to prevent omnibus-gitlab services (NGINX, Redis, Unicorn etc.) @@ -578,4 +574,5 @@ then you need to escape curly brackets or use single quoted string. For example `"/api/#\{API::API.version\}/session.json"` or `'/api/#{API::API.version}/session.json'` +### Setting up throttling for 'paths to be protected' @@ -581,5 +578,4 @@ -### Setting up throttling for 'paths to be protected' Use next options to control throttling 'limit' and 'period': ```ruby diff --git a/doc/settings/database.md b/doc/settings/database.md index 313ff511fd8085f7dca36db45831fde14b6fd5b1_ZG9jL3NldHRpbmdzL2RhdGFiYXNlLm1k..8924ff5428f98910c39d88578d948a610dd9c1f9_ZG9jL3NldHRpbmdzL2RhdGFiYXNlLm1k 100644 --- a/doc/settings/database.md +++ b/doc/settings/database.md @@ -49,17 +49,17 @@ 1. Edit `/etc/gitlab/gitlab.rb`: - ```ruby - postgresql['ssl_cert_file'] = '/custom/path/to/server.crt' - postgresql['ssl_key_file'] = '/custom/path/to/server.key' - postgresql['ssl_ca_file'] = '/custom/path/to/bundle.pem' - postgresql['internal_certificate'] = "-----BEGIN CERTIFICATE----- - ...base64-encoded certificate... - -----END CERTIFICATE----- - " - postgresql['internal_key'] = "-----BEGIN RSA PRIVATE KEY----- - ...base64-encoded private key... - -----END RSA PRIVATE KEY----- - " - ``` + ```ruby + postgresql['ssl_cert_file'] = '/custom/path/to/server.crt' + postgresql['ssl_key_file'] = '/custom/path/to/server.key' + postgresql['ssl_ca_file'] = '/custom/path/to/bundle.pem' + postgresql['internal_certificate'] = "-----BEGIN CERTIFICATE----- + ...base64-encoded certificate... + -----END CERTIFICATE----- + " + postgresql['internal_key'] = "-----BEGIN RSA PRIVATE KEY----- + ...base64-encoded private key... + -----END RSA PRIVATE KEY----- + " + ``` @@ -65,8 +65,8 @@ - Relative paths will be rooted from the PostgreSQL data directory - (`/var/opt/gitlab/postgresql/data` by default). + Relative paths will be rooted from the PostgreSQL data directory + (`/var/opt/gitlab/postgresql/data` by default). 1. [Reconfigure GitLab][] to apply the configuration changes. 1. Restart PostgreSQL for the changes to take effect: @@ -68,11 +68,11 @@ 1. [Reconfigure GitLab][] to apply the configuration changes. 1. Restart PostgreSQL for the changes to take effect: - ```sh - gitlab-ctl restart postgresql - ``` + ```sh + gitlab-ctl restart postgresql + ``` If PostgreSQL fails to start, check the logs (e.g. `/var/log/gitlab/postgresql/current`) for more details. @@ -89,9 +89,9 @@ 1. Restart PostgreSQL for the changes to take effect: - ```sh - gitlab-ctl restart postgresql - ``` + ```sh + gitlab-ctl restart postgresql + ``` If PostgreSQL fails to start, check the logs (e.g. `/var/log/gitlab/postgresql/current`) for more details. @@ -160,17 +160,17 @@ 1. Edit `/etc/gitlab/gitlab.rb`: - ```ruby - # Replication settings - postgresql['sql_replication_user'] = "gitlab_replicator" - postgresql['wal_level'] = "replica" - ... - ... - # Backup/Archive settings - postgresql['archive_mode'] = "on" - postgresql['archive_command'] = "/your/wal/archiver/here" - postgresql['archive_timeout'] = "60" - ``` + ```ruby + # Replication settings + postgresql['sql_replication_user'] = "gitlab_replicator" + postgresql['wal_level'] = "replica" + ... + ... + # Backup/Archive settings + postgresql['archive_mode'] = "on" + postgresql['archive_command'] = "/your/wal/archiver/here" + postgresql['archive_timeout'] = "60" + ``` 1. [Reconfigure GitLab][] for the changes to take effect. This will result in a database restart. @@ -185,7 +185,7 @@ 1. Edit `/etc/gitlab/gitlab.rb`: - ```ruby - # Disable the built-in Postgres - postgresql['enable'] = false + ```ruby + # Disable the built-in Postgres + postgresql['enable'] = false @@ -191,10 +191,10 @@ - # Fill in the connection details for database.yml - gitlab_rails['db_adapter'] = 'postgresql' - gitlab_rails['db_encoding'] = 'utf8' - gitlab_rails['db_host'] = '127.0.0.1' - gitlab_rails['db_port'] = 5432 - gitlab_rails['db_username'] = 'USERNAME' - gitlab_rails['db_password'] = 'PASSWORD' - ``` + # Fill in the connection details for database.yml + gitlab_rails['db_adapter'] = 'postgresql' + gitlab_rails['db_encoding'] = 'utf8' + gitlab_rails['db_host'] = '127.0.0.1' + gitlab_rails['db_port'] = 5432 + gitlab_rails['db_username'] = 'USERNAME' + gitlab_rails['db_password'] = 'PASSWORD' + ``` @@ -200,4 +200,4 @@ - Don't forget to remove the `#` comment characters at the beginning of these - lines. + Don't forget to remove the `#` comment characters at the beginning of these + lines. @@ -203,3 +203,3 @@ - **Note:** + **Note:** @@ -205,5 +205,5 @@ - - `/etc/gitlab/gitlab.rb` should have file permissions `0600` because it contains - plain-text passwords. - - Postgresql allows to listen on [multiple addresses](https://www.postgresql.org/docs/9.6/runtime-config-connection.html) + - `/etc/gitlab/gitlab.rb` should have file permissions `0600` because it contains + plain-text passwords. + - Postgresql allows to listen on [multiple addresses](https://www.postgresql.org/docs/9.6/runtime-config-connection.html) @@ -209,5 +209,5 @@ - If you use multiple addresses in `gitlab_rails['db_host']`, comma-separated, the first address in the list will be used for connection. + If you use multiple addresses in `gitlab_rails['db_host']`, comma-separated, the first address in the list will be used for connection. 1. [Reconfigure GitLab][] for the changes to take effect. @@ -236,9 +236,9 @@ 1. Add symbolic links to the non-packaged versions: - ```bash - ln -s /path/to/new/pg_dump /path/to/new/psql /opt/gitlab/bin/ - ``` + ```bash + ln -s /path/to/new/pg_dump /path/to/new/psql /opt/gitlab/bin/ + ``` 1. Check the versions: @@ -242,8 +242,8 @@ 1. Check the versions: - ``` - /opt/gitlab/bin/pg_dump --version - /opt/gitlab/bin/psql --version - ``` + ``` + /opt/gitlab/bin/pg_dump --version + /opt/gitlab/bin/psql --version + ``` @@ -249,5 +249,5 @@ - They should now be the same as your non-packaged external PostgreSQL. + They should now be the same as your non-packaged external PostgreSQL. After this is done, ensure that the backup and restore tasks are using the correct executables by running both the [backup][rake-backup] and @@ -406,6 +406,7 @@ You can follow the instructions for manually upgrading PostgreSQL to 10.7. For GitLab 12.0, we will be automatically upgrading the database to 10.7 unless specifically opted out. To opt out, run + ```shell sudo touch /etc/gitlab/disable-postgresql-upgrade ``` @@ -470,12 +471,12 @@ Follow the steps below to upgrade the database nodes 1. Secondary nodes must be upgraded before the primary node. - 1. On running `pg-upgrade` on a PG secondary node, the node will be removed - from the cluster. - 1. Once all the secondary nodes are upgraded using `pg-upgrade`, the user - will be left with a single-node cluster that has only the primary node. - 1. `pg-upgrade`, on secondary nodes will not update the existing data to - match the new version, as that data will be replaced by the data from - primary node. It will, however move the existing data to a backup - location. + 1. On running `pg-upgrade` on a PG secondary node, the node will be removed + from the cluster. + 1. Once all the secondary nodes are upgraded using `pg-upgrade`, the user + will be left with a single-node cluster that has only the primary node. + 1. `pg-upgrade`, on secondary nodes will not update the existing data to + match the new version, as that data will be replaced by the data from + primary node. It will, however move the existing data to a backup + location. 1. Once all secondary nodes are upgraded, run `pg-upgrade` on primary node. @@ -481,4 +482,4 @@ 1. Once all secondary nodes are upgraded, run `pg-upgrade` on primary node. - 1. On a primary node, `pg-upgrade` will update the existing data to match - the new PG version. + 1. On a primary node, `pg-upgrade` will update the existing data to match + the new PG version. 1. Recreate the secondary nodes by running the following command on each of them @@ -484,5 +485,7 @@ 1. Recreate the secondary nodes by running the following command on each of them - ```bash - gitlab-ctl repmgr standby setup MASTER_NODE_NAME - ``` + + ```bash + gitlab-ctl repmgr standby setup MASTER_NODE_NAME + ``` + 1. Check if the repmgr cluster is back to the original state @@ -488,10 +491,11 @@ 1. Check if the repmgr cluster is back to the original state - ```bash - gitlab-ctl repmgr cluster show - ``` + + ```bash + gitlab-ctl repmgr cluster show + ``` #### Troubleshooting upgrades in an HA cluster - If at some point, the bundled PostgreSQL had been running on a node before upgrading to an HA setup, the old data directory may remain. This will cause `gitlab-ctl reconfigure` to downgrade the version of the PostgreSQL utilities it uses on that node. Move (or remove) the directory to prevent this: - `mv /var/opt/gitlab/postgresql/data/ /var/opt/gitlab/postgresql/data.$(date +%s)` @@ -492,7 +496,8 @@ #### Troubleshooting upgrades in an HA cluster - If at some point, the bundled PostgreSQL had been running on a node before upgrading to an HA setup, the old data directory may remain. This will cause `gitlab-ctl reconfigure` to downgrade the version of the PostgreSQL utilities it uses on that node. Move (or remove) the directory to prevent this: - `mv /var/opt/gitlab/postgresql/data/ /var/opt/gitlab/postgresql/data.$(date +%s)` +### Upgrading a Geo instance @@ -498,8 +503,7 @@ -### Upgrading a Geo instance As of Gitlab 12.1, `gitlab-ctl pg-upgrade` can automatically upgrade the database on your GEO servers. NOTE: **Note:** Due to how PostgreSQL replication works, this cannot be done without the need to resynchronize your secondary database server. Therefore, this upgrade cannot be done without downtime. If you want to skip the automatic upgrade, before you install 12.1 or newer, run the following: @@ -500,9 +504,10 @@ As of Gitlab 12.1, `gitlab-ctl pg-upgrade` can automatically upgrade the database on your GEO servers. NOTE: **Note:** Due to how PostgreSQL replication works, this cannot be done without the need to resynchronize your secondary database server. Therefore, this upgrade cannot be done without downtime. If you want to skip the automatic upgrade, before you install 12.1 or newer, run the following: + ```shell sudo touch /etc/gitlab/disable-postgresql-upgrade ``` @@ -510,6 +515,7 @@ To upgrade a GEO cluster, you will need a name for the replication slot, and the password to connect to the primary server. 1. To find the existing name of the replication slot name on the primary node, run: + ```shell sudo gitlab-psql -qt -c 'select slot_name from pg_replication_slots' ``` @@ -519,6 +525,7 @@ 1. Upgrade the gitlab-ee package on the secondary server 1. Re-initialize the database on the secondary server using the command + ```shell sudo gitlab-ctl replicate-geo-database --slot-name=SECONDARY_SLOT_NAME --host=PRIMARY_HOST_NAME ``` @@ -522,6 +529,7 @@ ```shell sudo gitlab-ctl replicate-geo-database --slot-name=SECONDARY_SLOT_NAME --host=PRIMARY_HOST_NAME ``` + You will be prompted for the password of the primary server. 1. Navigate to `https://your_primary_server/admin/geo/nodes` and ensure that all nodes are healthy @@ -538,7 +546,7 @@ ### Set `default_transaction_isolation` into `read committed` -If you see errors similar to the following in your production/sidekiq log: +If you see errors similar to the following in your production/sidekiq log: ``` ActiveRecord::StatementInvalid PG::TRSerializationFailure: ERROR: could not serialize access due to concurrent update @@ -549,9 +557,9 @@ connecting to your PostgreSQL database and run `SHOW default_transaction_isolation;`. GitLab application expects `read committed` to be configured. -This `default_transaction_isolation` configuration is set in your -`postgresql.conf` file. You will need to restart/reload the database once you -changed the configuration. This configuration comes by default in the packaged +This `default_transaction_isolation` configuration is set in your +`postgresql.conf` file. You will need to restart/reload the database once you +changed the configuration. This configuration comes by default in the packaged PostgreSQL server included with GitLab Omnibus. ### Connecting to the bundled PostgreSQL database diff --git a/doc/settings/logs.md b/doc/settings/logs.md index 313ff511fd8085f7dca36db45831fde14b6fd5b1_ZG9jL3NldHRpbmdzL2xvZ3MubWQ=..8924ff5428f98910c39d88578d948a610dd9c1f9_ZG9jL3NldHRpbmdzL2xvZ3MubWQ= 100644 --- a/doc/settings/logs.md +++ b/doc/settings/logs.md @@ -152,4 +152,5 @@ sidekiq['log_format'] = 'default' gitlab_pages['log_format'] = 'text' ``` + [ee]: https://about.gitlab.com/gitlab-ee/ diff --git a/doc/settings/nginx.md b/doc/settings/nginx.md index 313ff511fd8085f7dca36db45831fde14b6fd5b1_ZG9jL3NldHRpbmdzL25naW54Lm1k..8924ff5428f98910c39d88578d948a610dd9c1f9_ZG9jL3NldHRpbmdzL25naW54Lm1k 100644 --- a/doc/settings/nginx.md +++ b/doc/settings/nginx.md @@ -232,5 +232,5 @@ 1. **Disable bundled Nginx** - In `/etc/gitlab/gitlab.rb` set: + In `/etc/gitlab/gitlab.rb` set: @@ -236,7 +236,7 @@ - ```ruby - nginx['enable'] = false - ``` + ```ruby + nginx['enable'] = false + ``` 1. **Set the username of the non-bundled web-server user** @@ -240,8 +240,8 @@ 1. **Set the username of the non-bundled web-server user** - By default, omnibus-gitlab has no default setting for the external webserver - user, you have to specify it in the configuration. For Debian/Ubuntu the - default user is `www-data` for both Apache/Nginx whereas for RHEL/CentOS - the Nginx user is `nginx`. + By default, omnibus-gitlab has no default setting for the external webserver + user, you have to specify it in the configuration. For Debian/Ubuntu the + default user is `www-data` for both Apache/Nginx whereas for RHEL/CentOS + the Nginx user is `nginx`. @@ -247,3 +247,3 @@ - *Note: Make sure you have first installed Apache/Nginx so the webserver user is created, otherwise omnibus will fail while reconfiguring.* + *Note: Make sure you have first installed Apache/Nginx so the webserver user is created, otherwise omnibus will fail while reconfiguring.* @@ -249,4 +249,4 @@ - Let's say for example that the webserver user is `www-data`. - In `/etc/gitlab/gitlab.rb` set: + Let's say for example that the webserver user is `www-data`. + In `/etc/gitlab/gitlab.rb` set: @@ -252,5 +252,5 @@ - ```ruby - web_server['external_users'] = ['www-data'] - ``` + ```ruby + web_server['external_users'] = ['www-data'] + ``` @@ -256,3 +256,3 @@ - *Note: This setting is an array so you can specify more than one user to be added to gitlab-www group.* + *Note: This setting is an array so you can specify more than one user to be added to gitlab-www group.* @@ -258,3 +258,3 @@ - Run `sudo gitlab-ctl reconfigure` for the change to take effect. + Run `sudo gitlab-ctl reconfigure` for the change to take effect. @@ -260,3 +260,3 @@ - *Note: if you are using SELinux and your web server runs under a restricted SELinux profile you may have to [loosen the restrictions on your web server][selinuxmod].* + *Note: if you are using SELinux and your web server runs under a restricted SELinux profile you may have to [loosen the restrictions on your web server][selinuxmod].* @@ -262,5 +262,5 @@ - *Note: make sure that the webserver user has the correct permissions on all directories used by external web-server, otherwise you will receive `failed (XX: Permission denied) while reading upstream` errors. + *Note: make sure that the webserver user has the correct permissions on all directories used by external web-server, otherwise you will receive `failed (XX: Permission denied) while reading upstream` errors. 1. **Add the non-bundled web-server to the list of trusted proxies** @@ -264,6 +264,6 @@ 1. **Add the non-bundled web-server to the list of trusted proxies** - Normally, omnibus-gitlab defaults the list of trusted proxies to what was - configured in the `real_ip` module for the bundled NGINX. + Normally, omnibus-gitlab defaults the list of trusted proxies to what was + configured in the `real_ip` module for the bundled NGINX. @@ -269,5 +269,5 @@ - For non-bundled web-servers the list needs to be configured directly, and should - include the IP address of your web-server if it is not on the same machine as GitLab. - Otherwise, users will be shown as being signed in from your web-server's IP address. + For non-bundled web-servers the list needs to be configured directly, and should + include the IP address of your web-server if it is not on the same machine as GitLab. + Otherwise, users will be shown as being signed in from your web-server's IP address. @@ -273,7 +273,7 @@ - ```ruby - gitlab_rails['trusted_proxies'] = [ '192.168.1.0/24', '192.168.2.1', '2001:0db8::/32' ] - ``` + ```ruby + gitlab_rails['trusted_proxies'] = [ '192.168.1.0/24', '192.168.2.1', '2001:0db8::/32' ] + ``` 1. **(Optional) Set the right gitlab-workhorse settings if using Apache** @@ -277,5 +277,5 @@ 1. **(Optional) Set the right gitlab-workhorse settings if using Apache** - *Note: The values below were added in GitLab 8.2, make sure you have the latest version installed.* + *Note: The values below were added in GitLab 8.2, make sure you have the latest version installed.* @@ -281,5 +281,5 @@ - Apache cannot connect to a UNIX socket but instead needs to connect to a - TCP Port. To allow gitlab-workhorse to listen on TCP (by default port 8181) - edit `/etc/gitlab/gitlab.rb`: + Apache cannot connect to a UNIX socket but instead needs to connect to a + TCP Port. To allow gitlab-workhorse to listen on TCP (by default port 8181) + edit `/etc/gitlab/gitlab.rb`: @@ -285,6 +285,6 @@ - ``` - gitlab_workhorse['listen_network'] = "tcp" - gitlab_workhorse['listen_addr'] = "127.0.0.1:8181" - ``` + ``` + gitlab_workhorse['listen_network'] = "tcp" + gitlab_workhorse['listen_addr'] = "127.0.0.1:8181" + ``` @@ -290,5 +290,5 @@ - Run `sudo gitlab-ctl reconfigure` for the change to take effect. + Run `sudo gitlab-ctl reconfigure` for the change to take effect. 1. **Download the right web server configs** @@ -292,12 +292,12 @@ 1. **Download the right web server configs** - Go to [GitLab recipes repository][recipes-web] and look for the omnibus - configs in the webserver directory of your choice. Make sure you pick the - right configuration file depending whether you choose to serve GitLab with - SSL or not. The only thing you need to change is `YOUR_SERVER_FQDN` with - your own FQDN and if you use SSL, the location where your SSL keys currently - reside. You also might need to change the location of your log files. + Go to [GitLab recipes repository][recipes-web] and look for the omnibus + configs in the webserver directory of your choice. Make sure you pick the + right configuration file depending whether you choose to serve GitLab with + SSL or not. The only thing you need to change is `YOUR_SERVER_FQDN` with + your own FQDN and if you use SSL, the location where your SSL keys currently + reside. You also might need to change the location of your log files. ## Setting the NGINX listen address or addresses @@ -468,8 +468,8 @@ - If you're adding a new location, you might need to include - ```conf - proxy_cache off; - proxy_pass http://gitlab-workhorse; - ``` + ```conf + proxy_cache off; + proxy_pass http://gitlab-workhorse; + ``` @@ -475,5 +475,5 @@ - in the string or in the included nginx config. Without these, any sub-location - will return a 404. See - [gitlab-ce#30619](https://gitlab.com/gitlab-org/gitlab-ce/issues/30619). + in the string or in the included nginx config. Without these, any sub-location + will return a 404. See + [gitlab-ce#30619](https://gitlab.com/gitlab-org/gitlab-ce/issues/30619). - You cannot add the root `/` location or the `/assets` location as those already @@ -479,5 +479,5 @@ - You cannot add the root `/` location or the `/assets` location as those already - exist in `gitlab-http.conf`. + exist in `gitlab-http.conf`. ## Inserting custom settings into the NGINX config @@ -682,6 +682,7 @@ error_page 502 /502.html; } ``` + Don't forget to update 'git.example.com' in the above example to be your server url. **Note:** If you wind up with a 403 forbidden, it's possible that you haven't enabled passenger in /etc/nginx/nginx.conf, to do so simply uncomment: @@ -689,6 +690,7 @@ ``` # include /etc/nginx/passenger.conf; ``` + then, 'sudo service nginx reload' ## Enabling/Disabling nginx_status diff --git a/doc/settings/prometheus.md b/doc/settings/prometheus.md index 313ff511fd8085f7dca36db45831fde14b6fd5b1_ZG9jL3NldHRpbmdzL3Byb21ldGhldXMubWQ=..8924ff5428f98910c39d88578d948a610dd9c1f9_ZG9jL3NldHRpbmdzL3Byb21ldGhldXMubWQ= 100644 --- a/doc/settings/prometheus.md +++ b/doc/settings/prometheus.md @@ -6,19 +6,21 @@ To configure a remote remote read or write service, you can include the following in `gitlab.rb`. - prometheus['remote_write'] = [ - { - url: 'https://some-remote-write-service.example.com', - basic_auth: { - password: 'remote write secret password' - } - } - ] - prometheus['remote_read'] = [ - { - url: 'https://some-remote-write-service.example.com' - } - ] +``` +prometheus['remote_write'] = [ + { + url: 'https://some-remote-write-service.example.com', + basic_auth: { + password: 'remote write secret password' + } + } +] +prometheus['remote_read'] = [ + { + url: 'https://some-remote-write-service.example.com' + } +] +``` For more documentation on the options available, see the [remote write] and [remote read] sections of the official documentation. @@ -36,7 +38,9 @@ No rules: - prometheus['rules_files'] = [] +``` +prometheus['rules_files'] = [] +``` Custom list: @@ -40,7 +44,9 @@ Custom list: - prometheus['rules_files'] = ['/path/to/rules/*.rules', '/path/to/single/file.rules'] +``` +prometheus['rules_files'] = ['/path/to/rules/*.rules', '/path/to/single/file.rules'] +``` ## node_exporter @@ -50,9 +56,11 @@ To disable the `mountstats` collector, adjust gitlab.rb with the following setting and run `gitlab-ctl reconfigure`: - node_exporter['flags'] = { - 'collector.mountstats' => false, - } +``` +node_exporter['flags'] = { + 'collector.mountstats' => false, +} +``` For more information on available collectors, see the [upstream documentation](https://github.com/prometheus/node_exporter#collectors). @@ -65,4 +73,3 @@ [alerting]: https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/ [recording]: https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/ - diff --git a/doc/settings/redis.md b/doc/settings/redis.md index 313ff511fd8085f7dca36db45831fde14b6fd5b1_ZG9jL3NldHRpbmdzL3JlZGlzLm1k..8924ff5428f98910c39d88578d948a610dd9c1f9_ZG9jL3NldHRpbmdzL3JlZGlzLm1k 100644 --- a/doc/settings/redis.md +++ b/doc/settings/redis.md @@ -44,9 +44,9 @@ issues) for use with GitLab you can do so using GitLab Omnibus. > **Note:** Redis does not require authentication by default. See - [Redis Security](http://redis.io/topics/security) documentation for more - information. We recommend using a combination of a Redis password and tight - firewall rules to secure your Redis service. +> [Redis Security](http://redis.io/topics/security) documentation for more +> information. We recommend using a combination of a Redis password and tight +> firewall rules to secure your Redis service. 1. Download/install GitLab Omnibus using **steps 1 and 2** from [GitLab downloads](https://about.gitlab.com/downloads). Do not complete other @@ -55,6 +55,6 @@ Be sure to change the `external_url` to match your eventual GitLab front-end URL: - ```ruby - external_url 'https://gitlab.example.com' + ```ruby + external_url 'https://gitlab.example.com' @@ -60,4 +60,4 @@ - # Disable all services except Redis - redis_master_role['enable'] = true + # Disable all services except Redis + redis_master_role['enable'] = true @@ -63,5 +63,5 @@ - # Redis configuration - redis['port'] = 6379 - redis['bind'] = '0.0.0.0' + # Redis configuration + redis['port'] = 6379 + redis['bind'] = '0.0.0.0' @@ -67,5 +67,5 @@ - # If you wish to use Redis authentication (recommended) - redis['password'] = 'Redis Password' - gitlab_rails['redis_password'] = 'Redis Password' + # If you wish to use Redis authentication (recommended) + redis['password'] = 'Redis Password' + gitlab_rails['redis_password'] = 'Redis Password' @@ -71,6 +71,6 @@ - # Disable automatic database migrations - # Only the primary GitLab application server should handle migrations - gitlab_rails['auto_migrate'] = false - ``` + # Disable automatic database migrations + # Only the primary GitLab application server should handle migrations + gitlab_rails['auto_migrate'] = false + ``` @@ -76,7 +76,7 @@ - > **Note:** The `redis_master_role['enable']` option is only available as of - GitLab 8.14, see [`gitlab_rails.rb`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/libraries/gitlab_rails.rb) - to understand which services are automatically disabled via that option. + > **Note:** The `redis_master_role['enable']` option is only available as of + > GitLab 8.14, see [`gitlab_rails.rb`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/libraries/gitlab_rails.rb) + > to understand which services are automatically disabled via that option. 1. Run `sudo gitlab-ctl reconfigure` to install and configure Redis. @@ -110,9 +110,9 @@ 1. Create a dedicated instance for each persistence class as per the instructions in [Setting up a Redis-only server](#setting-up-a-redis-only-server) 1. Set the appropriate variable in `/etc/gitlab/gitlab.rb` for each instance you are using: - ```ruby - gitlab_rails['redis_cache_instance'] = REDIS_CACHE_URL - gitlab_rails['redis_queues_instance'] = REDIS_QUEUES_URL - gitlab_rails['redis_shared_state_instance'] = REDIS_SHARED_STATE_URL - ``` + ```ruby + gitlab_rails['redis_cache_instance'] = REDIS_CACHE_URL + gitlab_rails['redis_queues_instance'] = REDIS_QUEUES_URL + gitlab_rails['redis_shared_state_instance'] = REDIS_SHARED_STATE_URL + ``` @@ -118,9 +118,10 @@ - **Note**: Redis URLs should be in the format: "redis://:PASSWORD@REDIS_HOST:PORT/2" - Where - * PASSWORD is the plaintext password for the Redis instance - * REDIS_HOST is the hostname or IP address of the host - * REDIS_PORT is the port Redis is listening on, the default is 6379 + **Note**: Redis URLs should be in the format: "redis://:PASSWORD@REDIS_HOST:PORT/2" + + Where: + - PASSWORD is the plaintext password for the Redis instance + - REDIS_HOST is the hostname or IP address of the host + - REDIS_PORT is the port Redis is listening on, the default is 6379 1. Run `gitlab-ctl reconfigure` @@ -172,9 +173,9 @@ 1. Add the following line to `/etc/gitlab/gitlab.rb`: - ```ruby - gitlab_rails['redis_ssl'] = true - ``` + ```ruby + gitlab_rails['redis_ssl'] = true + ``` 1. Run `sudo gitlab-ctl reconfigure` for the changes to take effect. @@ -195,8 +196,8 @@ 1. If you see messages that look like: - ``` - 2018-11-14_05:52:16.71123 time="2018-11-14T05:52:16Z" level=info msg="redis: dialing" address="redis-server:6379" scheme=rediss - 2018-11-14_05:52:16.74397 time="2018-11-14T05:52:16Z" level=error msg="unknown error" error="keywatcher: x509: certificate signed by unknown authority" - ``` + ``` + 2018-11-14_05:52:16.71123 time="2018-11-14T05:52:16Z" level=info msg="redis: dialing" address="redis-server:6379" scheme=rediss + 2018-11-14_05:52:16.74397 time="2018-11-14T05:52:16Z" level=error msg="unknown error" error="keywatcher: x509: certificate signed by unknown authority" + ``` @@ -202,7 +203,7 @@ - The first line should show `rediss` as the scheme with the address - of the Redis server. The second line indicates the certificate is - not properly trusted on this server. See the [previous section](#ssl-certificates). + The first line should show `rediss` as the scheme with the address + of the Redis server. The second line indicates the certificate is + not properly trusted on this server. See the [previous section](#ssl-certificates). 1. Verify that the SSL certificate is working via [these troubleshooting steps](ssl.md#custom-certificates-missing-or-skipped). @@ -218,10 +219,10 @@ 1. If you see messages that look like: - ``` - 2018-11-14_06:18:43.81636 time="2018-11-14T06:18:43Z" level=info msg="redis: dialing" address="redis-server:6379" scheme=rediss - 2018-11-14_06:18:43.86929 time="2018-11-14T06:18:43Z" level=error msg="unknown error" error="keywatcher: pubsub receive: NOAUTH Authentication required." - ``` + ``` + 2018-11-14_06:18:43.81636 time="2018-11-14T06:18:43Z" level=info msg="redis: dialing" address="redis-server:6379" scheme=rediss + 2018-11-14_06:18:43.86929 time="2018-11-14T06:18:43Z" level=error msg="unknown error" error="keywatcher: pubsub receive: NOAUTH Authentication required." + ``` 1. Check that the Redis client password specified in `/etc/gitlab/gitlab.rb` is correct: @@ -225,9 +226,9 @@ 1. Check that the Redis client password specified in `/etc/gitlab/gitlab.rb` is correct: - ```ruby - gitlab_rails['redis_password'] = 'your-password-here' - ``` + ```ruby + gitlab_rails['redis_password'] = 'your-password-here' + ``` 1. If you are using the Omnibus-provided Redis server, check that the server has the same password: @@ -231,9 +232,9 @@ 1. If you are using the Omnibus-provided Redis server, check that the server has the same password: - ```ruby - redis['password'] = 'your-password-here' - ``` + ```ruby + redis['password'] = 'your-password-here' + ``` ### Redis connection reset (ECONNRESET) @@ -245,10 +246,10 @@ 1. Check that the server is actually listening to the port via SSL. For example: - ```sh - /opt/gitlab/embedded/bin/openssl s_client -connect redis-server:6379 - ``` + ```sh + /opt/gitlab/embedded/bin/openssl s_client -connect redis-server:6379 + ``` 1. Check `/var/opt/gitlab/gitlab-rails/etc/resque.yml`. You should see something like: @@ -251,11 +252,11 @@ 1. Check `/var/opt/gitlab/gitlab-rails/etc/resque.yml`. You should see something like: - ```yaml - production: - url: rediss://:mypassword@redis-server:6379/ - ``` + ```yaml + production: + url: rediss://:mypassword@redis-server:6379/ + ``` 1. If `redis://` is present instead of `rediss://`, the `redis_ssl` parameter may not have been configured properly, or the reconfigure diff --git a/doc/settings/rpi.md b/doc/settings/rpi.md index 313ff511fd8085f7dca36db45831fde14b6fd5b1_ZG9jL3NldHRpbmdzL3JwaS5tZA==..8924ff5428f98910c39d88578d948a610dd9c1f9_ZG9jL3NldHRpbmdzL3JwaS5tZA== 100644 --- a/doc/settings/rpi.md +++ b/doc/settings/rpi.md @@ -4,7 +4,6 @@ recommend using a Pi 3 for best results. The Pi 1 and Pi Zero do not have enough RAM to make running GitLab feasible. - ## Configure Swap Even with a newer Pi, the first setting you will want to change is to ensure @@ -13,8 +12,7 @@ > On Raspbian, Swap can be configured in `/etc/dphys-swapfile`. > See [the manpage](http://manpages.ubuntu.com/manpages/bionic/man8/dphys-swapfile.8.html#config) for available settings. - ## Reduce running processes Once you have installed the GitLab package, you should change the following settings before running reconfigure. @@ -17,8 +15,7 @@ ## Reduce running processes Once you have installed the GitLab package, you should change the following settings before running reconfigure. - ```ruby # Reduce the number of running workers to the minimum in order to reduce memory usage unicorn['worker_processes'] = 2 diff --git a/doc/settings/smtp.md b/doc/settings/smtp.md index 313ff511fd8085f7dca36db45831fde14b6fd5b1_ZG9jL3NldHRpbmdzL3NtdHAubWQ=..8924ff5428f98910c39d88578d948a610dd9c1f9_ZG9jL3NldHRpbmdzL3NtdHAubWQ= 100644 --- a/doc/settings/smtp.md +++ b/doc/settings/smtp.md @@ -29,4 +29,5 @@ ``` ## Example configurations + ### SMTP on localhost @@ -32,4 +33,5 @@ ### SMTP on localhost + This configuration, which simply enables SMTP and otherwise uses the default settings, can be used for an MTA running on localhost that does not provide a `sendmail` interface or that provides a `sendmail` interface that is incompatible with GitLab, such as Exim. ```ruby @@ -37,6 +39,7 @@ ``` ### SMTP without SSL + By default SSL is enabled for SMTP. If your SMTP server do not support communication over SSL use following settings: ```ruby @@ -340,7 +343,7 @@ gitlab_rails['smtp_authentication'] = "login" gitlab_rails['smtp_enable_starttls_auto'] = true ``` - + ### Strato.de ```ruby @@ -403,6 +406,7 @@ gitlab_rails['smtp_tls'] = false gitlab_rails['smtp_openssl_verify_mode'] = 'none' ``` + ### GoDaddy (No TLS) ```ruby @@ -561,6 +565,7 @@ gitlab_rails['smtp_tls'] = false gitlab_rails['gitlab_email_from'] = "example@example.com" ``` + ### Snel.com ```ruby diff --git a/doc/settings/ssl.md b/doc/settings/ssl.md index 313ff511fd8085f7dca36db45831fde14b6fd5b1_ZG9jL3NldHRpbmdzL3NzbC5tZA==..8924ff5428f98910c39d88578d948a610dd9c1f9_ZG9jL3NldHRpbmdzL3NzbC5tZA== 100644 --- a/doc/settings/ssl.md +++ b/doc/settings/ssl.md @@ -25,7 +25,7 @@ > **Note**: Introduced in GitLab version ***10.5*** and disabled by default. > Enabled by default in GitLab version ***10.7*** and later if `external_url` is set with the *https* protocol > and no certificates are configured. - +> > NOTE: **Note**: In order for Let's Encrypt verification to work correctly, ports 80 and 443 will > need to be accessible to the Let's Encrypt servers that run the validation. Also note that the validation > currently [does not work with non-standard ports](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3580). @@ -29,7 +29,7 @@ > NOTE: **Note**: In order for Let's Encrypt verification to work correctly, ports 80 and 443 will > need to be accessible to the Let's Encrypt servers that run the validation. Also note that the validation > currently [does not work with non-standard ports](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3580). - +> > CAUTION: **Caution:** > Administrators installing or upgrading to GitLab version ***10.7*** or later and do not plan on using > **Let's Encrypt** should set the following in `/etc/gitlab/gitlab.rb` to disable: @@ -43,7 +43,7 @@ ```ruby letsencrypt['enable'] = true # GitLab 10.5 and 10.6 require this option -external_url "https://gitlab.example.com" # Must use https protocol +external_url "https://gitlab.example.com" # Must use https protocol letsencrypt['contact_emails'] = ['foo@email.com'] # Optional ``` @@ -79,7 +79,7 @@ #### Automatic Let's Encrypt Renewal > **Note**: [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/2433) in [GitLab](https://about.gitlab.com/pricing/) ***10.7***. - +> > CAUTION: **Caution:** > Administrators installing or upgrading to GitLab version ***12.1*** or later and plan on using > their own **Let's Encrypt** certificate should set the following in `/etc/gitlab/gitlab.rb` to @@ -115,6 +115,7 @@ ```sh # gitlab-ctl reconfigure ``` + ```sh # gitlab-ctl renew-le-certs ``` @@ -128,7 +129,7 @@ > ```ruby > letsencrypt['enable'] = false > ``` - +> > TIP: **Tip** > > The above commands require root privileges and only generate a renewal if the certificate is close to expiration. @@ -153,7 +154,7 @@ > NOTE: **Compatibility Note** > > Custom certificates were introduced in GitLab version **8.9**. - +> > TIP: **Further Reading** > > For installations that use self-signed certificates, Omnibus-GitLab