diff options
Diffstat (limited to 'doc/administration')
| -rw-r--r-- | doc/administration/auth/crowd.md | 68 | ||||
| -rw-r--r-- | doc/administration/auth/img/crowd_application.png | bin | 0 -> 55811 bytes | |||
| -rw-r--r-- | doc/administration/container_registry.md | 98 | ||||
| -rw-r--r-- | doc/administration/high_availability/database.md | 4 | ||||
| -rw-r--r-- | doc/administration/high_availability/load_balancer.md | 6 | ||||
| -rw-r--r-- | doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md | 2 | ||||
| -rw-r--r-- | doc/administration/monitoring/prometheus/index.md | 53 | ||||
| -rw-r--r-- | doc/administration/pages/index.md | 47 | ||||
| -rw-r--r-- | doc/administration/pages/source.md | 102 | ||||
| -rw-r--r-- | doc/administration/reply_by_email.md | 60 | ||||
| -rw-r--r-- | doc/administration/repository_storage_paths.md | 15 |
11 files changed, 375 insertions, 80 deletions
diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md new file mode 100644 index 00000000000..2c289c67a6d --- /dev/null +++ b/doc/administration/auth/crowd.md @@ -0,0 +1,68 @@ +# Atlassian Crowd OmniAuth Provider + +## Configure a new Crowd application + +1. Choose 'Applications' in the top menu, then 'Add application'. +1. Go through the 'Add application' steps, entering the appropriate details. + The screenshot below shows an example configuration. + +  + +## Configure GitLab + +1. On your GitLab server, open the configuration file. + + **Omnibus:** + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + **Source:** + + ```sh + cd /home/git/gitlab + + sudo -u git -H editor config/gitlab.yml + ``` + +1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) + for initial settings. + +1. Add the provider configuration: + + **Omnibus:** + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "crowd", + "args" => { + "crowd_server_url" => "CROWD_SERVER_URL", + "application_name" => "YOUR_APP_NAME", + "application_password" => "YOUR_APP_PASSWORD" + } + } + ] + ``` + + **Source:** + + ``` + - { name: 'crowd', + args: { + crowd_server_url: 'CROWD_SERVER_URL', + application_name: 'YOUR_APP_NAME', + application_password: 'YOUR_APP_PASSWORD' } } + ``` +1. Change `CROWD_SERVER_URL` to the URL of your Crowd server. +1. Change `YOUR_APP_NAME` to the application name from Crowd applications page. +1. Change `YOUR_APP_PASSWORD` to the application password you've set. +1. Save the configuration file. +1. [Reconfigure][] or [restart][] for the changes to take effect if you + installed GitLab via Omnibus or from source respectively. + +On the sign in page there should now be a Crowd tab in the sign in form. + +[reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure +[restart]: ../restart_gitlab.md#installations-from-source diff --git a/doc/administration/auth/img/crowd_application.png b/doc/administration/auth/img/crowd_application.png Binary files differnew file mode 100644 index 00000000000..7deea9dac8e --- /dev/null +++ b/doc/administration/auth/img/crowd_application.png diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md index 4d1cb391e69..dc4e57f25fb 100644 --- a/doc/administration/container_registry.md +++ b/doc/administration/container_registry.md @@ -483,12 +483,108 @@ If Registry is enabled in your GitLab instance, but you don't need it for your project, you can disable it from your project's settings. Read the user guide on how to achieve that. +## Disable Container Registry but use GitLab as an auth endpoint + +You can disable the embedded Container Registry to use an external one, but +still use GitLab as an auth endpoint. + +**Omnibus GitLab** +1. Open `/etc/gitlab/gitlab.rb` and set necessary configurations: + + ```ruby + registry['enable'] = false + gitlab_rails['registry_enabled'] = true + gitlab_rails['registry_host'] = "registry.gitlab.example.com" + gitlab_rails['registry_port'] = "5005" + gitlab_rails['registry_api_url'] = "http://localhost:5000" + gitlab_rails['registry_key_path'] = "/var/opt/gitlab/gitlab-rails/certificate.key" + gitlab_rails['registry_path'] = "/var/opt/gitlab/gitlab-rails/shared/registry" + gitlab_rails['registry_issuer'] = "omnibus-gitlab-issuer" + ``` + +1. Save the file and [reconfigure GitLab][] for the changes to take effect. + +**Installations from source** + +1. Open `/home/git/gitlab/config/gitlab.yml`, and edit the configuration settings under `registry`: + + ``` + ## Container Registry + + registry: + enabled: true + host: "registry.gitlab.example.com" + port: "5005" + api_url: "http://localhost:5000" + path: /var/opt/gitlab/gitlab-rails/shared/registry + key: /var/opt/gitlab/gitlab-rails/certificate.key + issuer: omnibus-gitlab-issuer + ``` + +1. Save the file and [restart GitLab][] for the changes to take effect. + ## Storage limitations Currently, there is no storage limitation, which means a user can upload an infinite amount of Docker images with arbitrary sizes. This setting will be configurable in future releases. +## Configure Container Registry notifications + +You can configure the Container Registry to send webhook notifications in +response to events happening within the registry. + +Read more about the Container Registry notifications config options in the +[Docker Registry notifications documentation][notifications-config]. + +>**Note:** +Multiple endpoints can be configured for the Container Registry. + + +**Omnibus GitLab installations** + +To configure a notification endpoint in Omnibus: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + registry['notifications'] = [ + { + 'name' => 'test_endpoint', + 'url' => 'https://gitlab.example.com/notify', + 'timeout' => '500ms', + 'threshold' => 5, + 'backoff' => '1s', + 'headers' => { + "Authorization" => ["AUTHORIZATION_EXAMPLE_TOKEN"] + } + } + ] + ``` + +1. Save the file and [reconfigure GitLab][] for the changes to take effect. + +--- + +**Installations from source** + +Configuring the notification endpoint is done in your registry config YML file created +when you [deployed your docker registry][registry-deploy]. + +Example: + +``` +notifications: + endpoints: + - name: alistener + disabled: false + url: https://my.listener.com/event + headers: <http.Header> + timeout: 500 + threshold: 5 + backoff: 1000 +``` + ## Changelog **GitLab 8.8 ([source docs][8-8-docs])** @@ -510,3 +606,5 @@ configurable in future releases. [registry-ssl]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/nginx/registry-ssl [existing-domain]: #configure-container-registry-under-an-existing-gitlab-domain [new-domain]: #configure-container-registry-under-its-own-domain +[notifications-config]: https://docs.docker.com/registry/notifications/ +[registry-notifications-config]: https://docs.docker.com/registry/configuration/#notifications
\ No newline at end of file diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md index e4f94eb7cb6..0a08591c3ce 100644 --- a/doc/administration/high_availability/database.md +++ b/doc/administration/high_availability/database.md @@ -16,7 +16,7 @@ If you use a cloud-managed service, or provide your own PostgreSQL: 1. Set up a `gitlab` username with a password of your choice. The `gitlab` user needs privileges to create the `gitlabhq_production` database. 1. Configure the GitLab application servers with the appropriate details. - This step is covered in [Configuring GitLab for HA](gitlab.md) + This step is covered in [Configuring GitLab for HA](gitlab.md). ## Configure using Omnibus @@ -105,6 +105,8 @@ If you use a cloud-managed service, or provide your own PostgreSQL: 1. Exit the database prompt by typing `\q` and Enter. 1. Exit the `gitlab-psql` user by running `exit` twice. 1. Run `sudo gitlab-ctl reconfigure` a final time. +1. Configure the GitLab application servers with the appropriate details. + This step is covered in [Configuring GitLab for HA](gitlab.md). --- diff --git a/doc/administration/high_availability/load_balancer.md b/doc/administration/high_availability/load_balancer.md index dad8e956c0e..3245988fc14 100644 --- a/doc/administration/high_availability/load_balancer.md +++ b/doc/administration/high_availability/load_balancer.md @@ -19,8 +19,8 @@ you need to use with GitLab. ## GitLab Pages Ports If you're using GitLab Pages you will need some additional port configurations. -GitLab Pages requires a separate VIP. Configure DNS to point the -`pages_external_url` from `/etc/gitlab/gitlab.rb` at the new VIP. See the +GitLab Pages requires a separate virtual IP address. Configure DNS to point the +`pages_external_url` from `/etc/gitlab/gitlab.rb` at the new virtual IP address. See the [GitLab Pages documentation][gitlab-pages] for more information. | LB Port | Backend Port | Protocol | @@ -32,7 +32,7 @@ GitLab Pages requires a separate VIP. Configure DNS to point the Some organizations have policies against opening SSH port 22. In this case, it may be helpful to configure an alternate SSH hostname that allows users -to use SSH on port 443. An alternate SSH hostname will require a new VIP +to use SSH on port 443. An alternate SSH hostname will require a new virtual IP address compared to the other GitLab HTTP configuration above. Configure DNS for an alternate SSH hostname such as altssh.gitlab.example.com. diff --git a/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md b/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md index 86ef9d167e2..edb9c911aac 100644 --- a/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md +++ b/doc/administration/monitoring/prometheus/gitlab_monitor_exporter.md @@ -13,7 +13,7 @@ To enable the GitLab monitor exporter: 1. Add or find and uncomment the following line, making sure it's set to `true`: ```ruby - gitlab_monitor_exporter['enable'] = true + gitlab_monitor['enable'] = true ``` 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 3a394c561db..b2445d1c0e5 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -3,10 +3,9 @@ >**Notes:** - Prometheus and the various exporters listed in this page are bundled in the Omnibus GitLab package. Check each exporter's documentation for the timeline - they got added. For installations from source you will have to install - them yourself. Over subsequent releases additional GitLab metrics will be - captured. -- Prometheus services are off by default but will be on starting with GitLab 9.0. + they got added. For installations from source you will have to install them + yourself. Over subsequent releases additional GitLab metrics will be captured. +- Prometheus services are on by default with GitLab 9.0. - Prometheus and its exporters do not authenticate users, and will be available to anyone who can access them. @@ -26,26 +25,25 @@ dashboard tool like [Grafana]. ## Configuring Prometheus >**Note:** -Available since Omnibus GitLab 8.16. For installations from source you'll -have to install and configure it yourself. +For installations from source you'll have to install and configure it yourself. -To enable Prometheus: +Prometheus and it's exporters are on by default, starting with GitLab 9.0. +Prometheus will run as the `gitlab-prometheus` user and listen on +`http://localhost:9090`. Each exporter will be automatically be set up as a +monitoring target for Prometheus, unless individually disabled. + +To disable Prometheus and all of its exporters, as well as any added in the future: 1. Edit `/etc/gitlab/gitlab.rb` -1. Add or find and uncomment the following line, making sure it's set to `true`: +1. Add or find and uncomment the following line, making sure it's set to `false`: ```ruby - prometheus['enable'] = true + prometheus_monitoring['enable'] = false ``` 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to take effect -By default, Prometheus will run as the `gitlab-prometheus` user and listen on -`http://localhost:9090`. If the [node exporter](#node-exporter) service -has been enabled, it will automatically be set up as a monitoring target for -Prometheus. - ## Changing the port Prometheus listens on >**Note:** @@ -71,16 +69,14 @@ To change the address/port that Prometheus listens on: ## Viewing performance metrics -After you have [enabled Prometheus](#configuring-prometheus), you can visit -`http://localhost:9090` for the dashboard that Prometheus offers by default. +You can visit `http://localhost:9090` for the dashboard that Prometheus offers by default. >**Note:** If SSL has been enabled on your GitLab instance, you may not be able to access Prometheus on the same browser as GitLab due to [HSTS][hsts]. We plan to [provide access via GitLab][multi-user-prometheus], but in the interim there are some workarounds: using a separate browser for Prometheus, resetting HSTS, or -having [Nginx proxy it][nginx-custom-config]. Follow issue [#27069] for more -information. +having [Nginx proxy it][nginx-custom-config]. The performance data collected by Prometheus can be viewed directly in the Prometheus console or through a compatible dashboard tool. @@ -96,6 +92,24 @@ Sample Prometheus queries: - **Data transmitted:** `irate(node_network_transmit_bytes[5m])` - **Data received:** `irate(node_network_receive_bytes[5m])` +## Configuring Prometheus to monitor Kubernetes + +> Introduced in GitLab 9.0. + +If your GitLab server is running within Kubernetes, Prometheus will collect metrics from the Nodes in the cluster including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration][] to monitor them. + +To disable the monitoring of Kubernetes: + +1. Edit `/etc/gitlab/gitlab.rb` +1. Add or find and uncomment the following line and set it to `false`: + + ```ruby + prometheus['monitor_kubernetes'] = false + ``` + +1. Save the file and [reconfigure GitLab][reconfigure] for the changes to + take effect + ## Prometheus exporters There are a number of libraries and servers which help in exporting existing @@ -143,5 +157,6 @@ The GitLab monitor exporter allows you to measure various GitLab metrics. [prom-grafana]: https://prometheus.io/docs/visualization/grafana/ [scrape-config]: https://prometheus.io/docs/operating/configuration/#%3Cscrape_config%3E [reconfigure]: ../../restart_gitlab.md#omnibus-gitlab-reconfigure -[#27069]: https://gitlab.com/gitlab-org/gitlab-ce/issues/27069 [1261]: https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/1261 +[prometheus integration]: ../../../user/project/integrations/prometheus.md +[prometheus-cadvisor-metrics]: https://github.com/google/cadvisor/blob/master/docs/storage/prometheus.md diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 8de0cc5af5c..0c63b0b59a7 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -26,22 +26,24 @@ it works. --- -In the case of custom domains, the Pages daemon needs to listen on ports `80` -and/or `443`. For that reason, there is some flexibility in the way which you -can set it up: +In the case of [custom domains](#custom-domains) (but not +[wildcard domains](#wildcard-domains)), the Pages daemon needs to listen on +ports `80` and/or `443`. For that reason, there is some flexibility in the way +which you can set it up: -1. Run the pages daemon in the same server as GitLab, listening on a secondary IP. -1. Run the pages daemon in a separate server. In that case, the +1. Run the Pages daemon in the same server as GitLab, listening on a secondary IP. +1. Run the Pages daemon in a separate server. In that case, the [Pages path](#change-storage-path) must also be present in the server that - the pages daemon is installed, so you will have to share it via network. -1. Run the pages daemon in the same server as GitLab, listening on the same IP + the Pages daemon is installed, so you will have to share it via network. +1. Run the Pages daemon in the same server as GitLab, listening on the same IP but on different ports. In that case, you will have to proxy the traffic with a loadbalancer. If you choose that route note that you should use TCP load balancing for HTTPS. If you use TLS-termination (HTTPS-load balancing) the pages will not be able to be served with user provided certificates. For HTTP it's OK to use HTTP or TCP load balancing. -In this document, we will proceed assuming the first option. +In this document, we will proceed assuming the first option. If you are not +supporting custom domains a secondary IP is not needed. ## Prerequisites @@ -54,6 +56,7 @@ Before proceeding with the Pages configuration, you will need to: serve Pages under HTTPS. 1. (Optional but recommended) Enable [Shared runners](../../ci/runners/README.md) so that your users don't have to bring their own. +1. (Only for custom domains) Have a **secondary IP**. ### DNS configuration @@ -62,11 +65,13 @@ you need to add a [wildcard DNS A record][wiki-wildcard-dns] pointing to the host that GitLab runs. For example, an entry would look like this: ``` -*.example.io. 1800 IN A 1.1.1.1 +*.example.io. 1800 IN A 1.1.1.1 +*.example.io. 1800 IN AAAA 2001::1 ``` where `example.io` is the domain under which GitLab Pages will be served -and `1.1.1.1` is the IP address of your GitLab instance. +and `1.1.1.1` is the IPv4 address of your GitLab instance and `2001::1` is the +IPv6 address. If you don't have IPv6, you can omit the AAAA record. > **Note:** You should not use the GitLab domain to serve user pages. For more information @@ -102,6 +107,8 @@ The Pages daemon doesn't listen to the outside world. 1. [Reconfigure GitLab][reconfigure] +Watch the [video tutorial][video-admin] for this configuration. + ### Wildcard domains with TLS support >**Requirements:** @@ -136,7 +143,8 @@ outside world. In addition to the wildcard domains, you can also have the option to configure GitLab Pages to work with custom domains. Again, there are two options here: support custom domains with and without TLS certificates. The easiest setup is -that without TLS certificates. +that without TLS certificates. In either case, you'll need a secondary IP. If +you have IPv6 as well as IPv4 addresses, you can use them both. ### Custom domains @@ -148,7 +156,7 @@ that without TLS certificates. > URL scheme: `http://page.example.io` and `http://domain.com` -In that case, the pages daemon is running, Nginx still proxies requests to +In that case, the Pages daemon is running, Nginx still proxies requests to the daemon but the daemon is also able to receive requests from the outside world. Custom domains are supported, but no TLS. @@ -158,11 +166,12 @@ world. Custom domains are supported, but no TLS. pages_external_url "http://example.io" nginx['listen_addresses'] = ['1.1.1.1'] pages_nginx['enable'] = false - gitlab_pages['external_http'] = '1.1.1.2:80' + gitlab_pages['external_http'] = ['1.1.1.2:80', '[2001::2]:80'] ``` where `1.1.1.1` is the primary IP address that GitLab is listening to and - `1.1.1.2` the secondary IP where the GitLab Pages daemon listens to. + `1.1.1.2` and `2001::2` are the secondary IPs the GitLab Pages daemon + listens on. If you don't have IPv6, you can omit the IPv6 address. 1. [Reconfigure GitLab][reconfigure] @@ -177,7 +186,7 @@ world. Custom domains are supported, but no TLS. > URL scheme: `https://page.example.io` and `https://domain.com` -In that case, the pages daemon is running, Nginx still proxies requests to +In that case, the Pages daemon is running, Nginx still proxies requests to the daemon but the daemon is also able to receive requests from the outside world. Custom domains and TLS are supported. @@ -189,12 +198,13 @@ world. Custom domains and TLS are supported. pages_nginx['enable'] = false gitlab_pages['cert'] = "/etc/gitlab/ssl/example.io.crt" gitlab_pages['cert_key'] = "/etc/gitlab/ssl/example.io.key" - gitlab_pages['external_http'] = '1.1.1.2:80' - gitlab_pages['external_https'] = '1.1.1.2:443' + gitlab_pages['external_http'] = ['1.1.1.2:80', '[2001::2]:80'] + gitlab_pages['external_https'] = ['1.1.1.2:443', '[2001::2]:443'] ``` where `1.1.1.1` is the primary IP address that GitLab is listening to and - `1.1.1.2` the secondary IP where the GitLab Pages daemon listens to. + `1.1.1.2` and `2001::2` are the secondary IPs where the GitLab Pages daemon + listens on. If you don't have IPv6, you can omit the IPv6 address. 1. [Reconfigure GitLab][reconfigure] @@ -270,3 +280,4 @@ latest previous version. [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure [restart]: ../restart_gitlab.md#installations-from-source [gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.2.4 +[video-admin]: https://youtu.be/dD8c7WNcc6s diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 463715e48ca..a45c3306457 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -1,5 +1,9 @@ # GitLab Pages administration for source installations +>**Note:** +Before attempting to enable GitLab Pages, first make sure you have +[installed GitLab](../../install/installation.md) successfully. + This is the documentation for configuring a GitLab Pages when you have installed GitLab from source and not using the Omnibus packages. @@ -13,18 +17,47 @@ Pages to the latest supported version. ## Overview -[Read the Omnibus overview section.](index.md#overview) +GitLab Pages makes use of the [GitLab Pages daemon], a simple HTTP server +written in Go that can listen on an external IP address and provide support for +custom domains and custom certificates. It supports dynamic certificates through +SNI and exposes pages using HTTP2 by default. +You are encouraged to read its [README][pages-readme] to fully understand how +it works. -## Prerequisites +--- -Before proceeding with the Pages configuration, you will need to: +In the case of [custom domains](#custom-domains) (but not +[wildcard domains](#wildcard-domains)), the Pages daemon needs to listen on +ports `80` and/or `443`. For that reason, there is some flexibility in the way +which you can set it up: + +1. Run the Pages daemon in the same server as GitLab, listening on a secondary IP. +1. Run the Pages daemon in a separate server. In that case, the + [Pages path](#change-storage-path) must also be present in the server that + the Pages daemon is installed, so you will have to share it via network. +1. Run the Pages daemon in the same server as GitLab, listening on the same IP + but on different ports. In that case, you will have to proxy the traffic with + a loadbalancer. If you choose that route note that you should use TCP load + balancing for HTTPS. If you use TLS-termination (HTTPS-load balancing) the + pages will not be able to be served with user provided certificates. For + HTTP it's OK to use HTTP or TCP load balancing. + +In this document, we will proceed assuming the first option. If you are not +supporting custom domains a secondary IP is not needed. -1. Have a separate domain under which the GitLab Pages will be served. In this - document we assume that to be `example.io`. -1. Configure a **wildcard DNS record**. -1. (Optional) Have a **wildcard certificate** for that domain if you decide to - serve Pages under HTTPS. -1. (Optional but recommended) Enable [Shared runners](../../ci/runners/README.md) +## Prerequisites + +Before proceeding with the Pages configuration, make sure that: + +1. You have a separate domain under which GitLab Pages will be served. In + this document we assume that to be `example.io`. +1. You have configured a **wildcard DNS record** for that domain. +1. You have installed the `zip` and `unzip` packages in the same server that + GitLab is installed since they are needed to compress/uncompress the + Pages artifacts. +1. (Optional) You have a **wildcard certificate** for the Pages domain if you + decide to serve Pages (`*.example.io`) under HTTPS. +1. (Optional but recommended) You have configured and enabled the [Shared Runners][] so that your users don't have to bring their own. ### DNS configuration @@ -72,7 +105,7 @@ The Pages daemon doesn't listen to the outside world. cd /home/git sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git cd gitlab-pages - sudo -u git -H git checkout v0.2.4 + sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) sudo -u git -H make ``` @@ -97,14 +130,21 @@ The Pages daemon doesn't listen to the outside world. https: false ``` -1. Copy the `gitlab-pages-ssl` Nginx configuration file: +1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in + order to enable the pages daemon. In `gitlab_pages_options` the + `-pages-domain` must match the `host` setting that you set above. - ```bash - sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf - sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf + ``` + gitlab_pages_enabled=true + gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 ``` - Replace `gitlab-pages-ssl` with `gitlab-pages` if you are not using SSL. +1. Copy the `gitlab-pages` Nginx configuration file: + + ```bash + sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf + sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf + ``` 1. Restart NGINX 1. [Restart GitLab][restart] @@ -128,7 +168,7 @@ outside world. cd /home/git sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git cd gitlab-pages - sudo -u git -H git checkout v0.2.4 + sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) sudo -u git -H make ``` @@ -146,6 +186,17 @@ outside world. https: true ``` +1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in + order to enable the pages daemon. In `gitlab_pages_options` the + `-pages-domain` must match the `host` setting that you set above. + The `-root-cert` and `-root-key` settings are the wildcard TLS certificates + of the `example.io` domain: + + ``` + gitlab_pages_enabled=true + gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key + ``` + 1. Copy the `gitlab-pages-ssl` Nginx configuration file: ```bash @@ -153,12 +204,9 @@ outside world. sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf ``` - Replace `gitlab-pages-ssl` with `gitlab-pages` if you are not using SSL. - 1. Restart NGINX 1. [Restart GitLab][restart] - ## Advanced configuration In addition to the wildcard domains, you can also have the option to configure @@ -186,7 +234,7 @@ world. Custom domains are supported, but no TLS. cd /home/git sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git cd gitlab-pages - sudo -u git -H git checkout v0.2.4 + sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) sudo -u git -H make ``` @@ -221,12 +269,10 @@ world. Custom domains are supported, but no TLS. 1. Copy the `gitlab-pages-ssl` Nginx configuration file: ```bash - sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf - sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf + sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf + sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf ``` - Replace `gitlab-pages-ssl` with `gitlab-pages` if you are not using SSL. - 1. Edit all GitLab related configs in `/etc/nginx/site-available/` and replace `0.0.0.0` with `1.1.1.1`, where `1.1.1.1` the primary IP where GitLab listens to. @@ -254,7 +300,7 @@ world. Custom domains and TLS are supported. cd /home/git sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git cd gitlab-pages - sudo -u git -H git checkout v0.2.4 + sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) sudo -u git -H make ``` @@ -297,8 +343,6 @@ world. Custom domains and TLS are supported. sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf ``` - Replace `gitlab-pages-ssl` with `gitlab-pages` if you are not using SSL. - 1. Edit all GitLab related configs in `/etc/nginx/site-available/` and replace `0.0.0.0` with `1.1.1.1`, where `1.1.1.1` the primary IP where GitLab listens to. @@ -389,4 +433,6 @@ than GitLab to prevent XSS attacks. [pages-userguide]: ../../user/project/pages/index.md [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure [restart]: ../restart_gitlab.md#installations-from-source -[gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.2.4 +[gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.4.0 +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/init.d/gitlab.default.example +[shared runners]: ../../ci/runners/README.md diff --git a/doc/administration/reply_by_email.md b/doc/administration/reply_by_email.md index 00494e7e9d6..e99a7ee29cc 100644 --- a/doc/administration/reply_by_email.md +++ b/doc/administration/reply_by_email.md @@ -13,7 +13,8 @@ three strategies for this feature: ### Email sub-addressing -**If your provider or server supports email sub-addressing, we recommend using it.** +**If your provider or server supports email sub-addressing, we recommend using it. +Some features (e.g. create new issue via email) only work with sub-addressing.** [Sub-addressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing) is a feature where any email to `user+some_arbitrary_tag@example.com` will end up @@ -69,7 +70,9 @@ please consult [RFC 5322](https://tools.ietf.org/html/rfc5322#section-3.6.4). If you want to use Gmail / Google Apps with Reply by email, make sure you have [IMAP access enabled](https://support.google.com/mail/troubleshooter/1668960?hl=en#ts=1665018) -and [allowed less secure apps to access the account](https://support.google.com/accounts/answer/6010255). +and [allowed less secure apps to access the account](https://support.google.com/accounts/answer/6010255) +or [turn-on 2-step validation](https://support.google.com/accounts/answer/185839) +and use [an application password](https://support.google.com/mail/answer/185833). To set up a basic Postfix mail server with IMAP access on Ubuntu, follow the [Postfix setup documentation](reply_by_email_postfix_setup.md). @@ -138,12 +141,32 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow the # The IDLE command timeout. gitlab_rails['incoming_email_idle_timeout'] = 60 ``` + + ```ruby + # Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes mailbox incoming@exchange.example.com + gitlab_rails['incoming_email_enabled'] = true + + # The email address replies are sent to - Exchange does not support sub-addressing so %{key} is not used here + gitlab_rails['incoming_email_address'] = "incoming@exchange.example.com" + + # Email account username + # Typically this is the userPrincipalName (UPN) + gitlab_rails['incoming_email_email'] = "incoming@ad-domain.example.com" + # Email account password + gitlab_rails['incoming_email_password'] = "[REDACTED]" + + # IMAP server host + gitlab_rails['incoming_email_host'] = "exchange.example.com" + # IMAP server port + gitlab_rails['incoming_email_port'] = 993 + # Whether the IMAP server uses SSL + gitlab_rails['incoming_email_ssl'] = true + ``` -1. Reconfigure GitLab and restart mailroom for the changes to take effect: +1. Reconfigure GitLab for the changes to take effect: ```sh sudo gitlab-ctl reconfigure - sudo gitlab-ctl restart mailroom ``` 1. Verify that everything is configured correctly: @@ -230,6 +253,35 @@ To set up a basic Postfix mail server with IMAP access on Ubuntu, follow the # The IDLE command timeout. idle_timeout: 60 ``` + + ```yaml + # Configuration for Microsoft Exchange mail server w/ IMAP enabled, assumes mailbox incoming@exchange.example.com + incoming_email: + enabled: true + + # The email address replies are sent to - Exchange does not support sub-addressing so %{key} is not used here + address: "incoming@exchange.example.com" + + # Email account username + # Typically this is the userPrincipalName (UPN) + user: "incoming@ad-domain.example.com" + # Email account password + password: "[REDACTED]" + + # IMAP server host + host: "exchange.example.com" + # IMAP server port + port: 993 + # Whether the IMAP server uses SSL + ssl: true + # Whether the IMAP server uses StartTLS + start_tls: false + + # The mailbox where incoming mail will end up. Usually "inbox". + mailbox: "inbox" + # The IDLE command timeout. + idle_timeout: 60 + ``` 1. Enable `mail_room` in the init script at `/etc/default/gitlab`: diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index d6aa6101026..55a45119525 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -52,9 +52,12 @@ respectively. # Paths where repositories can be stored. Give the canonicalized absolute pathname. # NOTE: REPOS PATHS MUST NOT CONTAIN ANY SYMLINK!!! storages: # You must have at least a 'default' storage path. - default: /home/git/repositories - nfs: /mnt/nfs/repositories - cephfs: /mnt/cephfs/repositories + default: + path: /home/git/repositories + nfs: + path: /mnt/nfs/repositories + cephfs: + path: /mnt/cephfs/repositories ``` 1. [Restart GitLab] for the changes to take effect. @@ -75,9 +78,9 @@ working, you can remove the `repos_path` line. ```ruby git_data_dirs({ - "default" => "/var/opt/gitlab/git-data", - "nfs" => "/mnt/nfs/git-data", - "cephfs" => "/mnt/cephfs/git-data" + "default" => { "path" => "/var/opt/gitlab/git-data" }, + "nfs" => { "path" => "/mnt/nfs/git-data" }, + "cephfs" => { "path" => "/mnt/cephfs/git-data" } }) ``` |
