gitlab-org--gitlab-foss/doc/administration/container_registry.md

# GitLab Container Registry Administration

> **Note:**
This feature was [introduced][ce-4040] in GitLab 8.8.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Assumptions](#assumptions)
- [Container Registry domain configuration](#container-registry-domain-configuration)
    - [Container Registry under existing GitLab domain](#container-registry-under-existing-gitlab-domain)
    - [Container Registry under its own domain](#container-registry-under-its-own-domain)
- [Container Registry storage path](#container-registry-storage-path)
- [Disable Container Registry](#disable-container-registry)
- [Changelog](#changelog)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Assumptions

If you are using Omnibus, you have to bare in mind the following:

- The container Registry will be enabled by default if GitLab is configured
  with HTTPS and it will listen on port `5005`. If you want the Registry to
  listen on a port other than `5005` which is the default, read [#Container Registry under existing GitLab domain](#container-registry-under-existing-gitlab-domain)
  on how to achieve that. You will also have to configure your firewall to allow
  connections to that port.
- The Container Registry works under HTTPS by default. Note that using HTTP is
  possible but not recommended and out of the scope of this document,
  [see the insecure Registry documentation][docker-insecure] if you want to
  implement this.

## Container Registry domain configuration

There are two ways you can configure the container Registry domain. Either use
the existing GitLab domain where in that case the Registry will listen on a port,
or use a completely separate domain. Since the container Registry requires a
TLS certificate, in the end it all boils down to how easy or pricey is to
get a new TLS certificate.

1. If the Registry is configured to use its own domain, you will need a TLS
   certificate for that specific domain (e.g., `registry.example.com`) or maybe
   a wildcard certificate if hosted under a subdomain (e.g., `registry.gitlab.example.com`).
1. If the Registry is configured to use the existing GitLab domain, you can
   expose the Registry on a port so that you can reuse the existing GitLab TLS
   certificate.

Please take this into consideration before configuring the Container Registry
for the first time.

Read more about Docker Registry at https://docs.docker.com/registry/introduction/.

### 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 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 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.

## Disable Container Registry


## Changelog


[reconfigure gitlab]: ../../administration/restart_gitlab.md "How to restart GitLab documentation"
[wildcard certificate]: "https://en.wikipedia.org/wiki/Wildcard_certificate"
[ce-4040]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4040
[docker-insecure]: https://docs.docker.com/registry/insecure/