GitHub Container Registry, Proxy and Synology

Last week, I migrated a private application from Heroku to my Synology NAS (compatible with Docker). Thanks to GitHub Actions, every time the main branch of the project is updated, a new private “Docker image” is built and pushed to the GitHub Container Registry.

On the NAS, one may think that running this private (“dockerized”) application is just a matter of logging in to the GitHub Container Registry, pulling the image and creating a container. Correct, this works from the command line (over SSH).

Having said that, Synology DiskStation Manager (DSM) – the Operating System powering my NAS – offers a user interface (UI) to manage Docker images, containers, networks and registries. I tried to use this UI to add the GitHub Registry but it failed to load the list of images 😓

“Registry returned bad results” said DSM, sigh.

I don’t quite like when obvious things don’t work… Synology’s docs say both v1 and v2 registries are supported and the GitHub Container Registry supports Docker. Shortly after, I realized that the GitHub Container Registry didn’t fully implement the Docker Registry HTTP API.

Fortunately, I know a thing or two about containers, registries, etc. so I wrote a Container Registry Proxy to fix GitHub’s container registry for my use case¹. This proxy exposes two new API endpoints specified by the HTTP API v2 specification and it uses the GitHub REST API to retrieve the necessary data. All the other calls are transparently forwarded to the upstream GitHub registry.

This proxy only requires a GitHub token with the read:packages permission. It is written in Go and distributed as a lightweight Docker image published on the Docker Hub. Installing this proxy on a Synology NAS should therefore be straightforward since the Docker Hub registry is configured by default.

There are two caveats with this overall approach, though. First, the proxy registry should ideally be a local registry because Docker allows (insecure) local registries by default. Second, the DSM UI has some weird input validation rules that prevent http://127.0.0.1:10000 to be accepted as a “valid URL”. That is unfortunate because this address is our local registry… We must edit a configuration file directly on the NAS using SSH (more information about that on GitHub).

Once configured properly, this proxy works reasonably well.

The list of (Docker) registries in DSM. Both the Docker Hub and the local registry are configured. The local registry – named “GitHub Registry (Proxied)” – is in use.

The list of (Docker) images in DSM. The first image comes from the GitHub Registry via the local proxy registry. The other two are from the Docker Hub. The third/last image is the Container Registry Proxy introduced above.

I am not sure what the future of this small project is going to be since it does what I want already. Maybe some other known registries have similar issues? Or would there be any value in having that kind of proxy for other purposes, e.g., statistics, monitoring, etc.?