Add latest changes from gitlab-org/gitlab@master

2 files changed, 162 insertions, 0 deletions

diff --git a/doc/topics/airgap/index.md b/doc/topics/airgap/index.md
index abeb3a4b1d3..fc92dd5519d 100644
--- a/doc/topics/airgap/index.md
+++ b/doc/topics/airgap/index.md
@@ -3,6 +3,11 @@
 Computers in an air-gapped network are isolated from the public internet as a security measure.
 This page lists all the information available for running GitLab in an air-gapped environment.
 
+## Quick start
+
+If you plan to deploy a GitLab instance on a physically-isolated and offline network, see the
+[quick start guide](quick_start_guide.md) for configuration steps.
+
 ## Features
 
 Follow these best practices to use GitLab's features in an offline environment:
diff --git a/doc/topics/airgap/quick_start_guide.md b/doc/topics/airgap/quick_start_guide.md
new file mode 100644
index 00000000000..c4c02af3c85
--- /dev/null
+++ b/doc/topics/airgap/quick_start_guide.md
@@ -0,0 +1,157 @@
+# Getting started with an air-gapped GitLab Installation
+
+This is a step-by-step guide that helps you install, configure, and use a self-managed GitLab
+instance entirely offline.
+
+## Installation
+
+NOTE: **Note:**
+This guide assumes the server is Ubuntu 18.04. Instructions for other servers may vary.
+
+NOTE: **Note:**
+This guide assumes the server host resolves as `my-host`, which you should replace with your
+server's name.
+
+Follow the installation instructions [as outlined in the omnibus install
+guide](https://about.gitlab.com/install/#ubuntu), but make sure to specify an `http`
+URL for the `EXTERNAL_URL` installation step. Once installed, we will manually
+configure the SSL ourselves.
+
+It is strongly recommended to setup a domain for IP resolution rather than bind
+to the server's IP address. This better ensures a stable target for our certs' CN
+and will make long-term resolution simpler.
+
+```shell
+sudo EXTERNAL_URL="http://my-host.internal" install gitlab-ee
+```
+
+## Enabling SSL
+
+Follow these steps to enable SSL for your fresh instance. Note that these steps reflect those for
+[manually configuring SSL in Omnibus's NGINX configuration](https://docs.gitlab.com/omnibus/settings/nginx.html#manually-configuring-https):
+
+1. Make the following changes to `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   # Update external_url from "http" to "https"
+   external_url "https://example.gitlab.com"
+
+   # Set Let's Encrypt to false
+   letsencrypt['enable'] = false
+   ```
+
+1. Create the following directories with the appropriate permissions for generating self-signed
+   certificates:
+
+   ```shell
+   sudo mkdir -p /etc/gitlab/ssl
+   sudo chmod 755 /etc/gitlab/ssl
+   sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/gitlab/ssl/my-host.internal.key -out /etc/gitlab/ssl/my-host.internal.crt
+   ```
+
+1. Reconfigure your instance to apply the changes:
+
+   ```shell
+   sudo gitlab-ctl reconfigure
+   ```
+
+## Enabling the GitLab Container Registry
+
+Follow these steps to enable the container registry. Note that these steps reflect those for
+[configuring the container registry under an existing domain](../../administration/packages/container_registry.md#configure-container-registry-under-an-existing-gitlab-domain):
+
+1. Make the following changes to `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   # Change external_registry_url to match external_url, but append the port 4567
+   external_url "https://example.gitlab.com"
+   registry_external_url "https://example.gitlab.com:4567"
+   ```
+
+1. Reconfigure your instance to apply the changes:
+
+   ```shell
+   sudo gitlab-ctl reconfigure
+   ```
+
+## Allow the docker daemon to trust the registry and GitLab Runner
+
+Provide your Docker daemon with your certs by
+[following the steps for using trusted certificates with your registry](../../administration/packages/container_registry.md#using-self-signed-certificates-with-container-registry):
+
+```shell
+sudo mkdir -p /etc/docker/certs.d/my-host.internal:5000
+
+sudo cp /etc/gitlab/ssl/my-host.internal.crt /etc/docker/certs.d/my-host.internal:5000/ca.crt
+```
+
+Provide your GitLab Runner (to be installed next) with your certs by
+[following the steps for using trusted certificates with your Runner](https://docs.gitlab.com/runner/install/docker.html#installing-trusted-ssl-server-certificates):
+
+```shell
+sudo mkdir -p /etc/gitlab-runner/certs
+
+sudo cp /etc/gitlab/ssl/my-host.internal.crt /etc/gitlab-runner/certs/ca.crt
+```
+
+## Enabling GitLab Runner
+
+[Following a similar process to the steps for installing our GitLab Runner as a
+Docker service](https://docs.gitlab.com/runner/install/docker.html#docker-image-installation), we must first register our Runner:
+
+```shell
+$ sudo docker run --rm -it -v /etc/gitlab-runner:/etc/gitlab-runner gitlab/gitlab-runner register
+Updating CA certificates...
+Runtime platform                                    arch=amd64 os=linux pid=7 revision=1b659122 version=12.8.0
+Running in system-mode.
+
+Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/):
+https://my-host.internal
+Please enter the gitlab-ci token for this runner:
+XXXXXXXXXXX
+Please enter the gitlab-ci description for this runner:
+[eb18856e13c0]:
+Please enter the gitlab-ci tags for this runner (comma separated):
+
+Registering runner... succeeded                     runner=FSMwkvLZ
+Please enter the executor: custom, docker, virtualbox, kubernetes, docker+machine, docker-ssh+machine, docker-ssh, parallels, shell, ssh:
+docker
+Please enter the default Docker image (e.g. ruby:2.6):
+ruby:2.6
+Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
+```
+
+Now we must add some additional configuration to our runner:
+
+Make the following changes to `/etc/gitlab-runner/config.toml`:
+
+- Add docker socket to volumes `volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"]`
+- Add `pull_policy = "if-not-present"` to the executor configuration
+
+Now we can start our Runner:
+
+```shell
+sudo docker run -d --restart always --name gitlab-runner -v /etc/gitlab-runner:/etc/gitlab-runner -v /var/run/docker.sock:/var/run/docker.sock gitlab/gitlab-runner:latest
+90646b6587127906a4ee3f2e51454c6e1f10f26fc7a0b03d9928d8d0d5897b64
+```
+
+### Authenticating the registry against the host OS
+
+As noted in [Docker's registry authentication documentation](https://docs.docker.com/registry/insecure/#docker-still-complains-about-the-certificate-when-using-authentication),
+certain versions of Docker require trusting the certificate chain at the OS level.
+
+In the case of Ubuntu, this involves using `update-ca-certificates`:
+
+```shell
+sudo cp /etc/docker/certs.d/my-host.internal\:5000/ca.crt /usr/local/share/ca-certificates/my-host.internal.crt
+
+sudo update-ca-certificates
+```
+
+If all goes well, this is what you should see:
+
+```
+1 added, 0 removed; done.
+Running hooks in /etc/ca-certificates/update.d...
+done.
+```