Skip to content
Daniel Gietmann
← Blog
Coding

Running a private Docker registry with S3 as storage

dockerregistry starts the official Docker registry with login and S3 as storage, configured only through environment variables. How to start it, what the small Go launcher writes along the way, and the five places where you should be careful.

Anyone who builds their own Docker images needs a registry for them somewhere. The official registry from the distribution project can do that, but it wants a configuration file and, for the login, an htpasswd file with bcrypt hashes. You have to create both before the container starts.

dockerregistry takes that step off my hands. A small Go program reads the environment variables at startup, writes config.yml and htpasswd from them and then starts the official registry in version 2.8.3. The images end up in an S3 bucket, at AWS or a compatible provider such as MinIO or Cloudflare R2. No image data sits on the server's disk. This text refers to the state of main as of July 11, 2026 and to the published image 0.0.1.

Starting

Against a real S3 bucket, a single docker run is enough:

docker run -d --name registry -p 5000:5000 \
  -e REGISTRY_USER=admin \
  -e REGISTRY_PASSWORD='ein-langes-passwort' \
  -e S3_BUCKET=my-registry \
  -e S3_REGION=eu-central-1 \
  -e S3_ACCESS_KEY=... \
  -e S3_SECRET_KEY=... \
  ghcr.io/danielgtmn/dockerregistry:latest

After that you log in and push an image into it:

docker login localhost:5000
docker tag alpine:latest localhost:5000/alpine:latest
docker push localhost:5000/alpine:latest

The registry itself only speaks HTTP. For access from other machines, a reverse proxy with TLS belongs in front of it, such as Caddy or Traefik. For a provider other than AWS you additionally set S3_ENDPOINT. The launcher then switches to path-style addresses automatically (S3_FORCE_PATH_STYLE), because MinIO and similar services usually need that. For trying it out, there is a docker-compose.yml with MinIO in the repository.

What the launcher does

The program under cmd/danielgtmn-dockerregistry works through four steps:

  1. It reads the configuration. If S3_BUCKET or a login is missing, it aborts with a message. So without a login the registry does not start at all.
  2. It hashes the passwords with bcrypt and writes them to /auth/htpasswd, permissions 0600.
  3. It writes /etc/docker/registry/config.yml, also with 0600. It contains the S3 access, the login file, the delete permission and a health check for the storage every ten seconds.
  4. It removes its own variables such as REGISTRY_USER from the environment and replaces itself via exec with /bin/registry serve. The removal is necessary because the registry reads every variable that starts with REGISTRY_ as a setting.

You enter multiple users in REGISTRY_USERS, for example ci:geheim,daniel:anderes.

What to watch out for

The image on GHCR is older than the code

The image 0.0.1, which is also on GHCR as latest, was built from commit 0245f8c. A few minutes later, c487ead brought a change that fixes two things: redirects to S3 have been off by default since then, and the program's own variables are removed before the registry starts. In the published image, the configuration has redirect: disable: false hard-coded.

You notice this as soon as the bucket is not reachable for your clients, for example with a MinIO on the internal network. Then the registry redirects the client via 307 to an address it cannot reach, and the push fails. That is also how the commit message describes it. Until there is a new release, you build the image yourself from main:

git clone https://github.com/danielgtmn/dockerregistry
cd dockerregistry
docker build -t danielgtmn-dockerregistry .

All data runs through the registry

Since c487ead, redirects are off against real AWS S3 as well. Every pull then goes through your server, and its bandwidth is the limit. The distribution docs name this as a sensible choice when the storage is not nearby. If your clients reach the bucket directly, you can switch back with S3_REDIRECT=true. This variable is missing from the table in the README, it only appears in the program's help.

Every user may do everything

The login only knows user and password, no roles. Anyone who can log in may push, pull and delete, because DELETE_ENABLED is set to true here. The official registry has deletion switched off when nothing is configured. You cannot forbid individual users such as the CI from deleting. If you do not need it at all, set DELETE_ENABLED=false.

In REGISTRY_USERS, a comma separates the entries. A comma in the password splits the entry, and startup aborts with "invalid REGISTRY_USERS entry". A colon in the password, on the other hand, is allowed, the split only happens at the first one.

Deleting does not make the bucket smaller

When you remove old tags, for example with docker-cleanup, the registry only deletes the references. The layers stay in the bucket until a garbage collection runs. The image does not start one. The configuration is in the container, though, and this is how you start a trial run that deletes nothing:

docker exec registry registry garbage-collect --dry-run /etc/docker/registry/config.yml

For the real run without --dry-run, the distribution docs require the registry to be read-only or not running at all. Otherwise layers of an image that is being uploaded at that moment can be deleted along with the rest. This image has no switch for read-only mode. So schedule the run for a time when no CI is pushing.

Multiple instances need a shared secret

Without REGISTRY_HTTP_SECRET, the registry generates a random secret on every start. It uses it to sign state data that it stores on the client. With a single instance that is not a problem. If several run behind a load balancer, they must have the same secret according to the docs. Generate it once, for example with openssl rand -hex 32, and pass it to all instances.

What it is enough for

dockerregistry is a thin wrapper around the official registry. For a small team or your own projects that is enough: one container, one bucket, a few logins. If you need roles, a web UI or security scans, you are better served by Harbor or GitLab's Container Registry. Questions and bugs belong in the issues on GitHub.

Common questions

How do I start a private Docker registry with S3 as storage?
With dockerregistry, a single docker run with the environment variables REGISTRY_USER, REGISTRY_PASSWORD, S3_BUCKET, S3_REGION, S3_ACCESS_KEY and S3_SECRET_KEY is enough. For a provider other than AWS, such as MinIO or Cloudflare R2, you additionally set S3_ENDPOINT. The registry only speaks HTTP, so for access from other machines a reverse proxy with TLS belongs in front of it.
Why does the push fail with dockerregistry and MinIO on the internal network?
In the published image 0.0.1 of dockerregistry, redirects to S3 are hard-coded to on. If the bucket is not reachable for the client, the registry sends it via 307 to an address it cannot reach, and the push fails. Until there is a new release, you build the image yourself from main.
Does the S3 bucket get smaller when I delete tags in the Docker registry?
No. The registry only deletes the references, and the layers stay in the bucket until a garbage collection runs. The dockerregistry image does not start one, you call it yourself in the container with registry garbage-collect, ideally at a time when no CI is pushing.
Can I forbid individual users from deleting in dockerregistry?
No. The login of dockerregistry only knows user and password, no roles. Anyone who can log in may push, pull and delete. If you do not need deletion at all, you set DELETE_ENABLED=false.