You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: registry/part-1.md
+45-56
Original file line number
Diff line number
Diff line change
@@ -2,111 +2,103 @@
2
2
3
3
There are several ways to run a registry container. The simplest is to run an insecure registry over HTTP, but for that we need to configure Docker to explicitly allow insecure access to the registry.
4
4
5
-
## Testing the Registry Image
5
+
Docker expects all registries to run on HTTPS. The next section of this lab will introduce a secure version of our registry container, but for this part of the tutorial we will run a version on HTTP. When registering a image, Docker returns an error message like this:
6
+
```
7
+
http: server gave HTTP response to HTTPS client
8
+
```
9
+
The Docker Engine needs to be explicitly setup to use HTTP for the insecure registry. Edit or create `/etc/docker/docker` file:
10
+
```
11
+
$ sudo vi /etc/docker/docker
6
12
7
-
First we'll test that the registry image is working correctly, by running it without any special configuration:
- where `localhost`0 is the name of your machine, which can be found with the `hostname` command
8
17
9
18
```
10
-
docker run -d -p 5000:5000 --name registry registry:latest
19
+
$ hostname
11
20
```
12
-
## Understanding Image Names
13
21
22
+
Close and save the file, then restart the docker daemon.
23
+
```
24
+
$ sudo service docker restart
25
+
```
26
+
## Testing the Registry Image
27
+
First we'll test that the registry image is working correctly, by running it without any special configuration:
28
+
```
29
+
$ sudo docker run -d -p 5000:5000 --name registry registry:2
30
+
```
31
+
## Understanding Image Names
14
32
Typically we work with images from the Docker Hub, which is the default registry for the Docker Engine. Commands using just the image repository name work fine, like this:
15
-
16
33
```
17
-
docker pull nginx
34
+
$ sudo docker pull hello-world
18
35
```
19
-
20
-
`nginx` is the repository name, which we are using as a short form of the full image name. The full name is `docker.io/nginx:latest`. That breaks down into three parts:
36
+
`hello-world` is the repository name, which we are using as a short form of the full image name. The full name is `docker.io/hello-world:latest`. That breaks down into three parts:
21
37
22
38
-`docker.io` - the hostname of the registry which stores the image;
23
-
-`nginx` - the repository name, in this case in `{userName}/{imageName}` format;
39
+
-`hello-world` - the repository name, in this case in `{imageName}` format;
24
40
-`latest` - the image tag.
25
41
26
42
If a tag isn't specified, then the default `latest` is used. If a registry hostname isn't specified then the default `docker.io` for Docker Hub is used. If you want to use images with any other registry, you need to explicitly specify the hostname - the default is always Docker Hub, you can't change to a different default registry.
27
43
28
-
With a local registry, the hostname is the IP address or `localhost`, and the custom port used by the registry. The full registry address is `localhost:5000`.
44
+
With a local registry, the hostname and the custom port used by the registry is the full registry address, e.g. `<hostname>:5000`.
45
+
```
46
+
$ hostname
47
+
```
29
48
30
49
## Pushing and Pulling from the Local Registry
31
50
32
51
Docker uses the hostname from the full image name to determine which registry to use. We can build images and include the local registry hostname in the image tag, or use the `docker tag` command to add a new tag to an existing image.
33
52
34
-
These commands pull a public image from Docker Hub, tag it for use in the private registry with the full name `localhost:5000/labs/nginx`, and then push it to the registry:
53
+
These commands pull a public image from Docker Hub, tag it for use in the private registry with the full name `<hostname>:5000/hello-world`, and then push it to the registry:
35
54
36
55
```
37
-
docker pull nginx
38
-
docker tag nginx localhost:5000/labs/nginx:latest
39
-
docker push localhost:5000/labs/nginx:latest
56
+
$ sudo docker tag hello-world <hostname>:5000/hello-world
57
+
$ sudo docker push <hostname>:5000/hello-world
40
58
```
41
59
42
60
When you push the image to your local registry, you'll see similar output to when you push a public image to the Hub:
43
61
44
62
```
45
-
The push refers to a repository [localhost:5000/labs/nginx]
63
+
The push refers to a repository [<hostname>:5000/hello-world]
On the local machine, you can remove the new image tag and the original image, and pull it again from the local registry to verify it was correctly stored:
53
-
54
70
```
55
-
docker rmi localhost:5000/labs/nginx:latest
56
-
docker rmi nginx:latest
57
-
docker pull localhost:5000/labs/nginx:latest
71
+
$ sudo docker rmi <hostname>:5000/hello-world
72
+
$ sudo docker rmi hello-world
73
+
$ sudo docker pull <hostname>:5000/hello-world
58
74
```
59
-
60
75
That exercise shows the registry works correctly, but at the moment it's not very useful because all the image data is stored in the container's writable storage area, which will be lost when the container is removed. To store the data outside of the container, we need to mount a host directory when we start the container.
61
76
62
77
## Running a Registry Container with External Storage
63
-
64
78
Remove the existing registry container by removing the container which holds the storage layer. Any images pushed will be deleted:
65
-
66
79
```
67
-
docker kill registry
68
-
docker rm registry
80
+
$ sudo docker kill registry
81
+
$ sudo docker rm registry
69
82
```
70
-
71
83
In this example, the new container will use a host-mounted Docker volume. When the registry server in the container writes image layer data, it appears to be writing to a local directory in the container but it will be writing to a directory on the host.
72
84
73
-
The IP address needs to be specified to use the same IP the previous registry had, because that's what Docker Engine is configured to use, and it's how the images are tagged. The `-v` option maps the host folder, and the `--ip` option specifies an IP address. First, create a network to assign an IP address to the container:
Docker expects all registries to run on HTTPS. The next section of this lab will introduce a secure version of our registry container, but the current version runs on HTTP. When registering a image, Docker returns an error message like this:
92
-
```
93
-
http: server gave HTTP response to HTTPS client
94
-
```
95
-
The Docker Engine needs to be explicitly setup to use HTTP for the insecure registry. This can be set by clicking on 
96
-
97
-
`Preferences`
98
-
99
-
`Daemon` > `Insecure registries` and enter the IP address and port of the registry.
100
-
101
93
Tag and push the container with the new IP address of the registry.
102
94
```
103
-
docker tag nginx 192.168.127.128:5000/labs/nginx:latest
docker tag hello-world <hostname>:5000/hello-world
96
+
docker push <hostname>:5000/hellow-world
105
97
```
106
-
Repeating the previous `docker push` command uploads an image to the registry container, and the layers will be stored in the container's `/var/lib/registry` directory, which is actually mapped to the `$(pwd)/registry-data` directory on you local machine. The `tree` command will show the directory structure the registry server uses (if `tree` is not installed in OS X, `find` with also work):
98
+
Repeating the previous `docker push` command uploads an image to the registry container, and the layers will be stored in the container's `/var/lib/registry` directory, which is actually mapped to the `$(pwd)/registry-data` directory on you local machine. The `tree` command will show the directory structure the registry server uses:
107
99
108
100
```
109
-
registry-data find . -print | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
Storing data outside of the container means we can build a new version of the registry image and replace the old container with a new one using the same host mapping - so the new registry container has all the images stored by the previous container.
123
114
124
-
This container is still limited though. The container is accessible externally using the host's IP address, but that's different from the container's IP address - so you need to use different tags and a different engine configuration for external clients.
125
-
126
115
Using an insecure registry also isn't practical in multi-user scenarios. Effectively there's no security so anyone can push and pull images if they know the registry hostname. The registry server supports authentication, but only over a secure SSL connection. We'll run a secure version of the registry server in a container next.
Copy file name to clipboardExpand all lines: registry/part-2.md
+23-12
Original file line number
Diff line number
Diff line change
@@ -2,9 +2,8 @@
2
2
3
3
We saw how to run a simple registry container in [Part 1](part-1.md), using the official Docker registry image. The registry server con be configured to serve HTTPS traffic on a known domain, so it's straightforward to run a secure registry for private use with a self-signed SSL certificate.
4
4
5
-
## Generating the SSL Certificate
5
+
## Generating the SSL Certificate in Linux
6
6
7
-
### Create an SSL Certificate in Linux
8
7
The Docker docs explain how to [generate a self-signed certificate](https://docs.docker.com/registry/insecure/#/using-self-signed-certificates) on Linux using OpenSSL:
9
8
10
9
```
@@ -29,9 +28,22 @@ State or Province Name (full name) [Some-State]:
29
28
Locality Name (eg, city) []:
30
29
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Docker
31
30
Organizational Unit Name (eg, section) []:
32
-
Common Name (e.g. server FQDN or YOUR name) []:<host name>
31
+
Common Name (e.g. server FQDN or YOUR name) []:<hostname>
33
32
Email Address []:
34
33
```
34
+
If you are running the registry locally, be sure to use your host name as the CN.
35
+
36
+
To get the docker daemon to trust the certificate, copy the domain.crt file.
Now we have an SSL certificate and can run a secure registry.
36
48
37
49
## Running the Registry Securely
@@ -41,15 +53,15 @@ The registry server supports several configuration switches as environment varia
41
53
If you have an insecure registry container still running from [Part 2](part-2.md), remove it:
42
54
43
55
```
44
-
> docker kill registry
45
-
> docker rm registry
56
+
$ docker kill registry
57
+
$ docker rm registry
46
58
```
47
59
48
60
For the secure registry, we need to run a container which has the SSL certificate and key files available, which we'll do with an additional volume mount (so we have one volume for registry data, and one for certs). We also need to specify the location of the certificate files, which we'll do with environment variables:
@@ -68,12 +80,11 @@ We'll let Docker assign a random IP address to this container, because we'll be
68
80
69
81
## Accessing the Secure Registry
70
82
71
-
We're ready to run a secure registry now.
83
+
We're ready to push an image into our secure registry.
84
+
```
85
+
$ docker push <hostname>:5000/hello-world
86
+
$ docker pull <hostname>:5000/hello-world
72
87
```
73
-
> docker tag hello-world mylocalregistry:5000/hello-world
74
-
> docker push mylocalregistry:5000/hello-world
75
-
> docker pull mylocalregistry:5000/hello-world
76
-
77
88
We can go one step further with the open-source registry server, and add basic authentication - so we can require users to securely log in to push and pull images.
Copy file name to clipboardExpand all lines: registry/part-3.md
+23-24
Original file line number
Diff line number
Diff line change
@@ -4,23 +4,23 @@ From [Part 2](part-2.md) we have a registry running in a Docker container, which
4
4
5
5
## Usernames and Passwords
6
6
7
-
The registry server and the Docker client support [basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) over HTTPS. The server uses a file with a collection of usernames and encrypted passwords. The file uses a common standard from the Linux world - [Apache htpasswd].
7
+
The registry server and the Docker client support [basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) over HTTPS. The server uses a file with a collection of usernames and encrypted passwords. The file uses Apache's htpasswd.
8
8
9
-
Create the password file with an entry for user "moby" with password "DockerRules";
9
+
Create the password file with an entry for user "moby" with password "gordon";
-`-v $(pwd)/auth:/auth` - mount the local `auth` folder into the container, so the registry server can access `htpasswd` file;
53
52
-`-e REGISTRY_AUTH=htpasswd` - use the registry's `htpasswd` authentication method;
@@ -60,17 +59,17 @@ Now the registry is using secure transport and user authentication.
60
59
61
60
With basic authentication, users cannot push or pull from the registry unless they are authenticated. If you try and pull an image without authenticating, you will get an error:
Error response from daemon: Get https://registry.local:5000/v2/labs/hello-world/manifests/latest: no basic auth credentials
65
+
Error response from daemon: Get https://<hostname>:5000/v2/hello-world/manifests/latest: no basic auth credentials
67
66
```
68
67
69
68
The result is the same for valid and invalid image names, so you can't even check a repository exists without authenticating. Logging in to the registry is the same `docker login` command you use for Docker Hub, specifying the registry hostname:
70
69
71
-
```PowerShell
72
-
> docker login registry.local:5000
73
-
Username: elton
70
+
```
71
+
$ sudo docker login registry.local:5000
72
+
Username: moby
74
73
Password:
75
74
Login Succeeded
76
75
```
@@ -83,12 +82,12 @@ Error response from daemon: login attempt to https://registry.local:5000/v2/ fai
83
82
84
83
Now you're authenticated, you can push and pull as before:
Status: Image is up to date for registry.local:5000/labs/hello-world:latest
90
+
Status: Image is up to date for registry.local:5000/hello-world:latest
92
91
```
93
92
94
93
> Note. The open-source registry does not support the same authorization model as Docker Hub or Docker Trusted Registry. Once you are logged in to the registry, you can push and pull from any repository, there is no restriction to limit specific users to specific repositories.
0 commit comments