1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
# 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/
|
