sudo systemctl status nginx<\/pre>If not, run the following to install it on your VPS:<\/p>
sudo apt update\n\nsudo apt install nginx -y<\/pre>Configure Nginx as a reverse proxy<\/strong><\/p>Next, create a config file for Nginx:<\/p>
sudo nano \/etc\/nginx\/sites-available\/docker-registry<\/pre>And add the following:<\/p>
server {\n\nlisten 80;\n\nserver_name your-domain.com; # Add your domain here or leave as _ if no domain, or localhost\n\nlocation \/ {\n\n proxy_pass http:\/\/localhost:5000;\n\n proxy_set_header Host $host;\n\n proxy_set_header X-Real-IP $remote_addr;\n\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n\n proxy_set_header X-Forwarded-Proto $scheme;\n\n }\n\n}<\/pre>Note that HTTP forwarding to your domain name won’t work properly without a domain.<\/p>
Now you can enable the config:<\/p>
sudo ln -s \/etc\/nginx\/sites-available\/docker-registry \/etc\/nginx\/sites-enabled\/<\/pre>And test and reload Nginx:<\/p>
sudo nginx -t\n\nsudo systemctl reload nginx<\/pre>You can also test for proper forwarding by running:<\/p>
curl http:\/\/your-vps-ip\/v2\/_catalog<\/pre>You should get a JSON response listing the repositories in your own private Docker registry.<\/p>
Configure Nginx to handle HTTPS requests for the registry.<\/strong><\/p>For this step to be successful, you’ll need:<\/p>
\nYour Docker registry already running on your VPS at localhost:5000<\/strong>,<\/li>\n\n\n\nA domain or subdomain pointing to your VPS IP,<\/li>\n\n\n\n Your Nginx config enabled,<\/li>\n\n\n\n Certbot.<\/li>\n<\/ul>Let’s begin by installing Certbot:<\/p>
sudo apt update\n\nsudo apt install certbot python3-certbot-nginx<\/pre>Now, we have to obtain an SSL certificate using Certbot:<\/p>
sudo certbot --nginx -d registry.yourdomain.com<\/pre>This will edit your Nginx config with SSL settings and create a secure HTTPS server block.<\/p>
In your config file, you can expect to see this:<\/p>
…\n\nserver {\n\nlisten 443 ssl;\n\nserver_name registry.yourdomain.com;\n\nssl_certificate \/etc\/letsencrypt\/live\/registry.yourdomain.com\/fullchain.pem;\n\nssl_certificate_key \/etc\/letsencrypt\/live\/registry.yourdomain.com\/privkey.pem;\n\n…<\/pre>As before, test and reload Nginx to conclude and ensure everything is up to date.<\/p>
sudo nginx -t\n\nsudo systemctl reload nginx<\/pre>Finally, use curl again to test that the forwarding works:<\/p>
curl -k https:\/\/registry.yourdomain.com\/v2\/_catalog<\/pre>You should get a JSON object such as:<\/p>
{\"repositories\": [ ]}<\/pre>If your run fails, make sure your private registry is running and that ports 80 and 443 are not blocked by your firewall.<\/p>
3. Increase file upload size in Nginx<\/h3> Increasing file upload size might be beneficial and even necessary if you are using larger Docker images, as Nginx’s default client_max_body_size<\/strong> is only 1 MB.<\/p>Adjusting upload size is pretty straightforward. For example, let’s imagine we want to set the limit to 2 GB. Open the Nginx config file again and add the following:<\/p>
server {\n\n…\n\n client_max_body_size 2G\n\n…\n\n}<\/pre>As usual, test and reload Nginx to make sure your changes are applied.<\/p>
sudo nginx -t\n\nsudo systemctl reload nginx<\/pre>In order to verify the new upload size limit, push an image to your registry that is larger than the default size of 1 MB:<\/p>
docker push registry.yourdomain.com\/your-image<\/pre>4. Authenticate users for the private registry<\/h3> Setting up authentication for your private registry is crucial to keeping your private images safe. With Nginx, you can set up HTTP authentication and create users with ad hoc credentials, thus deciding who has access to your Docker registry.<\/p>
Let’s do this by setting up the htpasswd<\/strong> utility within an authentication file and adding the accepted users and passwords. In order to obtain htpasswd<\/strong>, you’ll need to install the apache2-utils package:<\/p>sudo apt install apache2-utils -y<\/pre>You can now create an .htpasswd<\/strong> file as well as your very first user. Be sure to do this within your project directory:<\/p>mkdir -p .\/auth\n\nsudo htpasswd -c .\/auth\/htpasswd username<\/pre>To add new users, run the same command, without including -c<\/strong>.<\/p>Configure basic authentication<\/strong><\/p>To configure Nginx to require authentication, open your Nginx site config (e.g., \/etc\/nginx\/sites-available\/docker-registry<\/strong>) and add the following inside your location \/ <\/strong>block:<\/p>location \/ {\n\n…\n\nauth_basic \"Docker Registry Authentication\";\n\nauth_basic_user_file \/full\/path\/to\/docker-registry\/auth\/htpasswd;\n\n…\n\n}<\/pre>Replace \/full\/path\/to\/docker-registry\/auth\/htpasswd<\/strong> with the absolute path to your .htpasswd file on your VPS.<\/p>Now update your Docker compose file to include authentication:<\/p>
version: '3'\n\nservices:\n\n registry:\n\nimage: registry:2\n\nports:\n\n - \"5000:5000\"\n\nenvironment:\n\n - REGISTRY_AUTH=htpasswd\n\n - REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm\n\n - REGISTRY_AUTH_HTPASSWD_PATH=\/auth\/htpasswd\n\nvolumes:\n\n - .\/data:\/var\/lib\/registry\n\n - .\/auth:\/auth<\/pre>Restart your container to apply the changes, like so:<\/p>
docker-compose down\n\ndocker-compose up -d<\/pre>You must specifically set up Docker to trust your registry if it is not using a valid TLS\/SSL certificate (i.e., HTTP or a self-signed cert); otherwise, Docker will prevent any communication with it.<\/p>
If you’re using HTTPS with a valid certificate from Let’s Encrypt or similar, you can skip this step.<\/p>
Update the Docker daemon<\/strong><\/p>First off, open your daemon file.<\/p>
sudo nano \/etc\/docker\/daemon.json<\/pre>If it doesn’t exist, you can create it with:<\/p>
touch \/etc\/docker\/daemon.json<\/pre>Add the following to the JSON object:<\/p>
{\n\n…\n\n \"insecure-registries\": [\"your.domain:5000\"]\n\n…\n\n}<\/pre>If needed, you can replace your.registry.domain:5000<\/strong> with:<\/p>\nYour VPS public IP and port (such as 123.123.123.123:5000), or<\/li>\n\n\n\n A domain or a subdomain that points to your VPS (most common scenario)<\/li>\n\n\n\n localhost:5000 or 127.0.0.1:5000, if the Docker registry is on the same VPS (less common scenario)<\/li>\n<\/ul>Important note:<\/strong> use this only if you’re using HTTP or self-signed HTTPS certs.<\/p>Make sure to restart Docker to apply your changes:<\/p>
sudo systemctl restart docker<\/pre>6. Push and pull images from the private registry<\/h3> At this point, your registry should be running reliably and your clients should be able to trust it. You can now store and retrieve images securely. Below are a few additional tips.<\/p>
Log in to the registry via Docker CLI<\/strong><\/p>As we previously set up authentication, your registry will request that you log in. If you have not enabled authentication, Docker will skip this step for you. To log in, run:<\/p>
docker login your.registry.domain:5000<\/pre>Where your.registry.domain:5000<\/strong> is whatever domain, subdomain, or VPS public IP and port you have chosen.<\/p>At this point, you’ll be prompted to input the password and username you created. Docker will save your login information locally in ~\/.docker\/config.json<\/strong> if the login is successful.<\/p>Tag an image for the private registry<\/strong><\/p>To correctly deliver a desired image to your private registry, you need to tag it with the full registry address. You can do this by running the following:<\/p>
docker tag ubuntu:latest your.registry.domain:5000\/my-image:my-tag<\/pre>Where my-image<\/strong> is the name of your image, and my-tag<\/strong> is the tag you want to assign to it. If you omit the tag (i.e., :my-tag<\/strong>), Docker will default to using :latest<\/strong>.<\/p>Push and pull tagged images to the private registry<\/strong><\/p>After you are done tagging, your image is ready to be pushed to your Docker registry. At this stage, Docker will authenticate you (if authentication has been set up), connect to the registry, and upload your image layers:<\/p>
docker push your.registry.domain:5000\/my-image<\/pre>To pull the image, simply use the pull<\/strong> command:<\/p>docker pull your.registry.domain:5000\/my-image<\/pre>Docker will look for your image in the registry, cache it locally for usage, and pull it. Note that for this step to be successful, your registry needs to be running.<\/p>
Interacting with images in your Docker registry: example<\/strong><\/p>Let’s take a look at a comprehensive example of how to use your private registry.<\/p>
# Tag your image\n\ndocker tag nginx:latest your.registry.domain:5000\/my-image\n\n# Login if needed\n\ndocker login your.registry.domain:5000\n\n# Push your image\n\ndocker push your.registry.domain:5000\/my-image\n\n# On another machine (pointing to the same registry)\n\ndocker pull your.registry.domain:5000\/my-image\n\n# Browse what’s available in the registry\n\ncurl http:\/\/your.registry.domain:5000\/v2\/_catalog<\/pre>\n
\n\t\t\t\n\t\t\t\t<\/path>\n\t\t\t<\/svg>\n\t\t<\/button><\/figure><\/div>Conclusion<\/h2> In this guide, we have seen how to set up a private Docker registry to gain full control over those container images you wish to keep private. This also enhances security, keeping your images safe and distributing them with reduced risk, and reduces latency, making for a better development experience both in testing and production environments.<\/p>
By following the steps outlined in this guide, you can build a secure and efficient foundation for privately managing your container images and scaling your projects without worrying about security.<\/p>
![\"\"](\"https:\/\/imagedelivery.net\/LqiWLm-3MGbYHtFuUbcBtA\/wp-content\/uploads\/sites\/2\/2023\/02\/VPS-hosting-banner.png\/public\")
<\/a><\/figure>![\"Create](\"https:\/\/imagedelivery.net\/LqiWLm-3MGbYHtFuUbcBtA\/wp-content\/uploads\/sites\/2\/2025\/05\/docker-private-registry-image-example.jpg\/public\")