What is a local Docker registry?
A local Docker registry is a repository that allows you to store and manage your Docker images locally on your computer, rather than relying on a remote service like DockerHub. It's a great and simple alternative to self-hosting your own registry since you cannot skip a registry entirely when deploying with Kamal.
Advantages
They are 4 good benefits of a local registry:
-
Costs: You save on container images hosting. No more charges for DockerHub.
-
Speed: Pulling and pushing images to a local Docker registry can be quite a bit faster than accessing your current provider registry.
-
Security: A local registry minimizes the risk of exposing your images to the public internet. You can mitigate risks of leaking your environment variables and source code.
-
Simplicity: You reduce the amount of initial setup for self-hosting with Kamal. You save on one secret.
Disadvantages
The obvious disadvantage of a local registry is that it's, well, local to your Kamal installation. That means if you are using a local registry from on your laptop, you cannot easily share it with your coworkers.
How to use local registry
Note that this is currently unreleased feature so you would have to use Kamal's main branch.
To use a local Docker registry from Kamal, point to localhost
in your config/deploy.yml
like this:
# config/deploy.yml
registry:
server: "localhost:5555"
You can choose your own port, otherwise port 80 will be assumed. You don't need to provide KAMAL_REGISTRY_PASSWORD
anymore.
You should use this feature with Docker 28.3.3 and higher since the locally published ports would be accesible on the local network and not just on the loopback.
How does it work
Kamal will simply run a local registry
image on the desired port instead of logging in for an external registry. Registry is just an official Docker image for running a registry.
The CLI's login action is changed to reflect this. The new setup action is meant for both setting up a local registry or logging into an external one and similarly the logout action is now a combined remove action:
kamal registry login -> kamal registry setup
kamal registry logout -> kamal registry remove
Alternatives
As an alternative to a local registry you can always self-host a full Docker registry yourself like 37signals, the company behind Kamal. Authors of Kamal needed to avoid contracted bandwidth, reduce costs, and assume control since they self-host the rest on their own hardware.
A local registry is of course not enough. In the end, they chose Harbor for deploying their Docker registry after using DockerHub previously.
p.s. I made Kamal Handbook to help you start with Kamal.
