Articles

A private Docker registry

Host your own Docker registry with users and passwords in one JailOps jail. Two packages, a few lines of configuration, passwords from htpasswd, the images on a volume, and a firewall that lets in only who you choose.

The idea

A registry of your own, with users in a file.

Two programs do the work. docker-registry stores the images. docker_auth says who may push and pull: a user logs in there, gets a short-lived token, and shows it to the registry. Both live in one jail, the images live on a volume that outlives the jail, and the firewall of the jail lets in only the addresses you name.

Nothing else runs. The users are lines in a configuration file and the passwords are bcrypt hashes from htpasswd.

A jail and a volume

The images on a volume, so the jail stays disposable.

Make the volume first, then the jail, and attach the volume while the jail is stopped:

on the host
$ jailops volume create registry-data --comment "the images of the registry"
$ jailops create registry --image freebsd-15-1 --network lan --storage default --autostart --comment "a private Docker registry"
$ jailops volume attach registry registry-data /var/db/registry
$ jailops start registry

Delete or rebuild the jail whenever you like. The volume keeps every image.

Two packages

One from the ports, one from the JailOps repository.

docker-registry comes from the FreeBSD ports. docker-auth comes from the JailOps package repository, which the jail trusts once, with the key and the repository file described in the README of the repository. Then:

on the host
$ jailops exec registry -- pkg install -y docker-registry docker-auth
$ jailops shell registry

The rest of the page happens inside the jail, in that shell.

A key and a certificate

The server signs the tokens, the registry checks them.

docker_auth signs every token with a key of its own. The registry trusts the matching certificate. Make the pair once:

in the jail
# cd /usr/local/etc/docker_auth
# openssl req -x509 -newkey rsa:4096 -nodes -sha256 -days 3650 -subj "/CN=docker-auth.example.com" -keyout token.key -out token.crt
# chgrp docker_auth token.key && chmod 640 token.key

The two services also speak TLS, with the certificate of registry.example.com (from your own CA or from Let's Encrypt). Put it in the same directory as server.crt and its key as server.key, readable by the group docker_auth:

in the jail
# chgrp docker_auth server.key && chmod 640 server.key

Users and rules

A password hash and a few lines of rules.

A password is a bcrypt hash. Make it on any machine that has htpasswd (the package apache24 on FreeBSD, apache2-utils on Debian):

anywhere
$ htpasswd -nB alice
New password:
Re-type new password:
alice:$2y$05$s0meBcryptHashOfThePassword...

Everything after alice: goes into /usr/local/etc/docker_auth/auth_config.yml, next to the rules. Alice gets everything under her own name, and every logged-in user may pull library/*:

/usr/local/etc/docker_auth/auth_config.yml
server:
  addr: ":5001"
  certificate: "/usr/local/etc/docker_auth/server.crt"
  key: "/usr/local/etc/docker_auth/server.key"

token:
  issuer: "docker-auth.example.com"
  expiration: 900
  certificate: "/usr/local/etc/docker_auth/token.crt"
  key: "/usr/local/etc/docker_auth/token.key"

users:
  "alice":
    password: "$2y$05$s0meBcryptHashOfThePassword..."

acl:
  - match: {account: "/.+/", name: "${account}/*"}
    actions: ["*"]
    comment: "A user has full access to the images under the own name"
  - match: {account: "/.+/", name: "library/*"}
    actions: ["pull"]
    comment: "Every user can pull library/*"

The first rule that matches decides, and what no rule allows is refused. token.issuer must be the same text in the registry's configuration.

The registry

Point it at the login service.

The registry keeps its images on the volume, serves TLS, and sends every client to docker_auth for a token:

/usr/local/etc/docker-registry/config.yml
version: 0.1
log:
  fields:
    service: registry
storage:
  filesystem:
    rootdirectory: /var/db/registry
http:
  addr: :5000
  tls:
    certificate: /usr/local/etc/docker_auth/server.crt
    key: /usr/local/etc/docker_auth/server.key
auth:
  token:
    realm: https://registry.example.com:5001/auth
    service: registry
    issuer: docker-auth.example.com
    rootcertbundle: /usr/local/etc/docker_auth/token.crt

realm is the address clients are sent to, so it must be a name they can reach. issuer is the same text as in docker_auth.

Start both

Enabled now, and at every boot of the jail.

in the jail
# sysrc docker_auth_enable=YES docker_registry_enable=YES
# service docker_auth start
# service docker_registry start

Open the ports

Closed until you allow a source.

A jail answers nobody until a rule lets them in. Clients need both ports: 5000 for the registry and 5001 for the login. Name the addresses of your office as a set and let only them in:

on the host
$ jailops firewall address-set create office --address 192.0.2.0/24 --comment "the offices"
$ jailops firewall policy create registry --comment "the registry and its login service"
$ jailops firewall rule add registry in --port 5000 --from set:office --comment "the registry"
$ jailops firewall rule add registry in --port 5001 --from set:office --comment "the login of the registry"
$ jailops config set registry firewall.policies registry

Leave out --from to let everyone in. Check a connection before anyone tries it: jailops firewall test --from 192.0.2.7 --to jail:registry --port 5000.

Log in and push

From any machine with Docker.

on a client
$ docker login registry.example.com:5000
Username: alice
Password:
Login Succeeded
$ docker tag alpine registry.example.com:5000/alice/alpine
$ docker push registry.example.com:5000/alice/alpine

The login service checks the password, signs a token for what alice may do, and the registry lets the push through. Anyone else is refused.

One more user

One more line, and it takes effect.

Make the hash with htpasswd -nB bob, add "bob" under users: in auth_config.yml and save. docker_auth watches its file and reloads it when it changes; a file with a mistake is refused and the server keeps running with the old one.

See also

More articles

Try it on one server.

Try the console from the screenshots, install on a clean FreeBSD 15.1 machine, or add JailOps to a host you already run.