Initial docker container registry configuration docs.

1 files changed, 127 insertions, 0 deletions

diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md
new file mode 100644
index 00000000000..d89cfd1d43e
--- /dev/null
+++ b/doc/administration/container_registry.md
@@ -0,0 +1,127 @@
+# GitLab Container Registry Administration
+
+Documentation on how to use Container Registry are under [TODO](TODO.md).
+
+## Configuration
+
+Containers can be large in size and they are stored on the server GitLab is
+installed on.
+
+The Container Registry works under HTTPS by default.
+This means that the Container Registry requires a SSL certificate.
+There are two options on how this can be configured:
+
+1. Use its own domain - needs a SSL certificate for that specific domain
+(eg. registry.example.com) or a wildcard certificate if hosted under a subdomain
+(eg. registry.gitlab.example.com)
+1. Use existing GitLab domain and expose the registry on a port - can reuse
+existing GitLab SSL certificate
+
+Note that using HTTP is possible,
+[see insecure Registry document.](https://github.com/docker/distribution/blob/master/docs/insecure.md)
+
+Please take this into consideration before configuring Container Registry for
+the first time.
+
+## Container Registry under its own domain
+
+Lets assume that you want the Container Registry to be accessible at
+`https://registry.gitlab.example.com`.
+
+### Omnibus GitLab packages
+
+Place your SSL certificate and key in
+`/etc/gitlab/ssl/registry.gitlab.example.com.crt`
+and
+`/etc/gitlab/ssl/registry.gitlab.example.com.key` and make sure they have
+correct permissions:
+
+```bash
+chmod 600 /etc/gitlab/ssl/registry.gitlab.example.com.*
+```
+
+Once the SSL certificate is in place, edit `/etc/gitlab/gitlab.rb` with:
+
+```ruby
+registry_external_url 'https://registry.gitlab.example.com'
+```
+
+Save the file and [reconfigure GitLab][] for the changes to take effect.
+
+Users should now be able to login to the Container Registry using:
+
+```bash
+docker login registry.gitlab.example.com
+```
+
+with their GitLab credentials.
+
+If you have a [wildcard certificate][], you need to specify the path to the
+certificate in addition to the URL, in this case `/etc/gitlab/gitlab.rb` will
+look like:
+
+```ruby
+registry_external_url 'https://registry.gitlab.example.com'
+registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem"
+registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key"
+```
+
+## Container Registry under existing GitLab domain
+
+Lets assume that your GitLab instance is accessible at
+`https://gitlab.example.com`. You can expose the Container Registry under
+a separate port.
+
+Lets assume that you've exposed port `4567` in your network firewall.
+
+### Omnibus GitLab packages
+
+Your `/etc/gitlab/gitlab.rb` should contain the Container Registry URL as
+well as the path to the existing SSL certificate and key used by GitLab.
+
+```ruby
+registry_external_url 'https://gitlab.example.com:4567'
+
+## If your SSL certificate is not in /etc/gitlab/ssl/gitlab.example.com.crt
+## and key not in /etc/gitlab/ssl/gitlab.example.com.key uncomment the lines
+## below
+
+# registry_nginx['ssl_certificate'] = "/path/to/certificate.pem"
+# registry_nginx['ssl_certificate_key'] = "/path/to/certificate.key"
+```
+
+Save the file and [reconfigure GitLab][] for the changes to take effect.
+
+Users should now be able to login to the Container Registry using:
+
+```bash
+docker login gitlab.example.com:4567
+```
+
+with their GitLab credentials.
+
+## Container Registry storage path
+
+It is possible to change path where containers will be stored by the Container
+Registry.
+
+### Omnibus GitLab packages
+
+By default, the path Container Registry is using to store the containers is in
+`/var/opt/gitlab/gitlab-rails/shared/registry`.
+This path is accessible to the user running the Container Registry daemon,
+user running GitLab and to the user running Nginx web server.
+
+In `/etc/gitlab/gitlab.rb`:
+
+```ruby
+gitlab_rails['registry_path'] = "/path/to/registry/storage"
+```
+
+Save the file and [reconfigure GitLab][] for the changes to take effect.
+
+**NOTE** You should confirm that the GitLab, registry and the web server user
+have access to this directory.
+
+[reconfigure gitlab]: ../../administration/restart_gitlab.md "How to restart GitLab documentation"
+[wildcard certificate]: "https://en.wikipedia.org/wiki/Wildcard_certificate"