GitHub Container Registry, Proxy and SynologyClermont-Fd Area, France
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 😓
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 case1. 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
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
Once configured properly, this proxy works reasonably well.
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.?
Important: this works for me™ but that doesn’t mean all edge cases are handled. This might explain why GitHub isn’t fully compatible with the HTTP API v2 specification yet. I don’t know. ↩
Feel free to fork and edit this post if you find a typo, thank you so much! This post is licensed under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.
No comments here. You can interact on Mastodon or send me an email if you prefer.