Tools: How To Set Up a Private Docker Registry on Ubuntu

The author selected the Free and Open Source Fund to receive a donation as part of the Write for DOnations program. Docker Registry is an application that manages storing and delivering Docker container images. Registries centralize container images and reduce build times for developers. Docker images guarantee the same runtime environment through virtualization, but building an image can involve a significant time investment. For example, rather than installing dependencies and packages separately to use Docker, developers can download a compressed image from a registry that contains all of the necessary components. You can also automate pushing images to a registry using CI/CD pipelines or continuous integration tools to update images during production and development. Docker provides a free public registry, Docker Hub, that can host your custom Docker images. When you need to keep images private (for example, when using proprietary software), a self-hosted private Docker registry gives you full control over access, storage, and TLS. Images typically contain all the code necessary to run an application, so using a private registry is preferable for sensitive or internal workloads. In this tutorial, you will set up and secure your own private Docker Registry on Ubuntu. You will use Docker Compose to define the registry configuration and Nginx as a reverse proxy to forward traffic and terminate TLS. When you are done, you will be able to push and pull container images to and from your registry over HTTPS with authentication. Ubuntu version support: This tutorial has been validated on Ubuntu 20.04 LTS, 22.04 LTS, 24.04 LTS, and 24.10. The same steps and commands work across these versions. On Ubuntu 22.04 and later, use the docker compose (with a space) command; if you installed the legacy Compose V1, use docker-compose (with a hyphen) instead. Docker on the command line is useful when starting out and testing containers, but proves to be unwieldy for bigger deployments involving multiple containers running in parallel. With Docker Compose, you can write one .yml file to set up each container’s configuration and the information containers need to communicate with each other. You use the docker compose command (or docker-compose on legacy installs) to run and control all components as a group. Docker Registry is itself an application with multiple components, so you will use Docker Compose to manage it. To start an instance of the registry, you’ll set up a docker-compose.yml file to define it and the location on disk where your registry will be storing its data. You’ll store the configuration in a directory called docker-registry on the main server. Create it by running: Then, create a subdirectory called data, where your registry will store its images: Create and open a file called docker-compose.yml by running: Add the following lines, which define a basic instance of a Docker Registry: First, you name the service registry and set its image to registry:2. Under ports, you map host port 5000 to the container port 5000 so that requests to the server on port 5000 are forwarded to the registry. In the environment section, REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY tells the registry where to store data. In volumes, the host ./data directory is mounted at /data in the container so image layers are stored on the host filesystem. Save and close the file. Start the registry with: If your system uses the legacy Compose V1 binary, run docker-compose up instead. The registry container and its dependencies will be downloaded and started. You can ignore the No HTTP secret provided warning for this setup. For production with multiple registry instances behind a load balancer, set the REGISTRY_HTTP_SECRET environment variable to a shared random value (for example, from openssl rand -hex 32). The last line of the output shows the registry listening on port 5000. You can press CTRL+C to stop its execution. In this step, you have created a Docker Compose configuration that starts a Docker Registry listening on port 5000. In the next steps, you’ll expose it at your domain and set up authentication. As part of the prerequisites, you’ve enabled HTTPS at your domain. To expose your secured Docker Registry there, you’ll only need to configure Nginx to forward traffic from your domain to the registry container. You have already set up the /etc/nginx/sites-available/your_domain file, containing your server configuration. Open it for editing by running: Find the existing location block: You need to forward traffic to port 5000, where your registry will be listening for traffic. You also want to append headers to the request forwarded to the registry, which provides additional information from the server about the request itself. Replace the existing contents of the location block with the following lines: The if block checks the user agent of the request and verifies that the version of the Docker client is above 1.5, as well as that it’s not a Go application that’s trying to access. For more explanation on this, you can find the nginx header configuration in Docker’s registry Nginx guide. Save and close the file when you’re done. Apply the changes by restarting Nginx: If you get an error, double-check the configuration you’ve added. To confirm that Nginx is properly forwarding traffic to your registry container on port 5000, run the registry: Then, in a browser window, navigate to your domain and access the v2 endpoint, like so: You will see an empty JSON object: In your terminal, you’ll receive output similar to the following: You can see from the last line that a GET request was made to /v2/, which is the endpoint you sent a request to, from your browser. The container received the request you made, from the port forwarding, and returned a response of {}. The code 200 in the last line of the output means that the container handled the request successfully. Press CTRL+C to stop its execution. Now that you have set up port forwarding, you’ll move on to improving the security of your registry. Nginx allows you to set up HTTP authentication for the sites it manages, which you can use to limit access to your Docker Registry. To achieve this, you’ll create an authentication file with htpasswd and add username and password combinations to it that will be accepted. You can obtain the htpasswd utility by installing the apache2-utils package. Do so by running: You’ll store the authentication file with credentials under ~/docker-registry/auth. Create it by running: Create the first user, replacing username with the username you want to use. The -B flag orders the use of the bcrypt algorithm, which Docker requires: Enter the password when prompted, and the combination of credentials will be appended to registry.password. Note: To add more users, re-run the previous command without -c, which creates a new file: Now that the list of credentials is made, you’ll edit docker-compose.yml to order Docker to use the file you created to authenticate users. Open it for editing by running: Add the highlighted lines: You’ve added environment variables specifying the use of HTTP authentication and provided the path to the file htpasswd created. For REGISTRY_AUTH, you have specified htpasswd as its value, which is the authentication scheme you are using, and set REGISTRY_AUTH_HTPASSWD_PATH to the path of the authentication file. REGISTRY_AUTH_HTPASSWD_REALM signifies the name of htpasswd realm. You’ve also mounted the ./auth directory to make the file available inside the registry container. Save and close the file. You can now verify that your authentication works correctly. First, navigate to the main directory: Then, run the registry: In your browser, refresh the page for your domain. You’ll be asked for a username and password. After providing a valid combination of credentials, you’ll see an empty JSON object: This means that you’ve successfully authenticated and gained access to the registry. Exit by pressing CTRL+C. Your registry is now secured and can be accessed only after authentication. You’ll now configure it to run as a background process while being resilient to reboots by starting automatically. You can ensure that the registry container starts every time the system boots up, or after it crashes, by instructing Docker Compose to always keep it running. Open docker-compose.yml for editing: Add the following line under the registry block: Setting restart to always ensures that the container will survive reboots. When you’re done, save and close the file. Start the registry as a background process with: With your registry running in the background, you can freely close the SSH session, and the registry won’t be affected. Because Docker images may be very large in size, you’ll now increase the maximum file size that Nginx will accept for uploads. Before you can push an image to the registry, you need to ensure that your registry will be able to handle large file uploads. The default size limit of file uploads in Nginx is 1m, which is not nearly enough for Docker images. To raise it, you’ll modify the main Nginx config file, located at /etc/nginx/nginx.conf. Open it for editing by running: Find the http section, and add the following line: The client_max_body_size parameter is now set to 16384m, making the maximum upload size equal to 16GB. Save and close the file when you’re done. Restart Nginx to apply the configuration changes: You can now upload large images to your Docker Registry without Nginx blocking the transfer or erroring out. Now that your Docker Registry server is up and running, and accepting large file sizes, you can try pushing an image to it. Since you don’t have any images readily available, you’ll use the ubuntu image from Docker Hub, a public Docker Registry, to test. From your second, client server, run the following command to download the ubuntu image, run it, and get access to its shell: The -i and -t flags give you interactive shell access into the container. Once you’re in, create a file called SUCCESS by running: By creating this file, you have customized your container. You’ll later use it to check that you’re using exactly the same container. Exit the container shell by running: Now, create a new image from the container you’ve just customized: The new image is now available locally, and you’ll push it to your new container registry. First, you have to log in: When prompted, enter in a username and password combination that you’ve defined in step 3 of this tutorial. Once you’re logged in, rename the created image: Finally, push the newly tagged image to your registry: You’ll receive output similar to the following: You’ve verified that your registry handles user authentication by logging in, and allows authenticated users to push images to the registry. You’ll now try pulling the image from your registry. Now that you’ve pushed an image to your private registry, you’ll try pulling from it. On the main server, log in with the username and password you set up previously: Try pulling the test-image by running: Docker should download the image. Run the container with the following command: List the files present by running: You will see the SUCCESS file you’ve created earlier, confirming that its the same image you’ve created: Exit the container shell by running: Now that you’ve tested pushing and pulling images, you have a secure private registry for your container images. The differences between a private Docker registry and Docker Hub are summarized in the table below: Use a self-hosted private registry when you need full control, want no repository/pull rate limits, and require higher privacy or compliance. Docker Hub is convenient for public images or small-scale private projects. A private Docker registry is a server that stores and serves Docker (OCI) container images only to authenticated users. It implements the same push/pull API as Docker Hub but runs under your control, so you can keep proprietary or internal images off the public internet. Yes. The Docker Registry (the open-source application) is free. Running it on your own Ubuntu server incurs only the cost of the server and domain. Docker Hub’s private repositories are a paid product; a self-hosted registry has no per-repository fee. The Docker client refuses to send credentials or push/pull over plain HTTP by default. Using HTTPS (for example with Let’s Encrypt) encrypts traffic and allows the client to authenticate to your registry safely. For development, you can configure the client to allow an “insecure” HTTP registry, but that is not recommended for production. On the client machine, add the registry to the Docker daemon’s insecure registries list. Edit /etc/docker/daemon.json (or the equivalent on your OS), add "insecure-registries": ["your-registry.example.com:5000"], then restart Docker. Use only in non-production environments. The registry stores image data in the volume you mount (for example ./data). Back up that directory regularly (for example with rsync, a snapshot, or your host’s backup tool). Optionally, run the registry with a storage backend (e.g. S3) and back up that storage. Restore by restoring the data directory or storage and starting the registry again. Yes. This tutorial runs the registry behind Nginx as a reverse proxy. Nginx handles TLS termination, optional HTTP auth, and large uploads. The registry listens on port 5000; Nginx proxies HTTPS (443) to it. Other proxies (Caddy, HAProxy) work similarly. The Docker Registry container listens on port 5000 by default. In this setup, Nginx listens on 443 (HTTPS) and forwards requests to localhost:5000. Clients connect to your domain over 443, not directly to 5000. How do I delete images from a private registry? The registry does not delete image data when you docker rmi from a client; it only deletes when the registry’s garbage collection runs and no references remain. You can use the registry’s delete API (with auth) or a tool like registry-cli or the registry’s optional delete feature. After deleting manifests, run garbage collection (see Docker Registry configuration) so disk space is reclaimed. In this tutorial you set up your own private Docker Registry on Ubuntu, secured it with Nginx and Let’s Encrypt, added htpasswd authentication, and verified push and pull. You can use the same registry from CI/CD pipelines or from Kubernetes by logging in with the same credentials. For more on building images, see the Docker documentation on Dockerfile best practices. Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases. Learn more about our products I help Businesses scale with AI x SEO x (authentic) Content that revives traffic and keeps leads flowing | 3,000,000+ Average monthly readers on Medium | Sr Technical Writer @ DigitalOcean | Ex-Cloud Consultant @ AMEX | Ex-Site Reliability Engineer(DevOps)@Nutanix This textbox defaults to using Markdown to format your answer. You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link! how to setup a Docker Registry with LDAP Authentication You did not tell we need to redirect to https scheme after nginx proxy. Then… how can I delete the image from the private registry? How can I change this private registry to a cache proxy ? How to list and delete images from registry? Please complete your information! Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation. Full documentation for every DigitalOcean product. The Wave has everything you need to know about building a business, from raising funding to marketing your product. Stay up to date by signing up for DigitalOcean’s Infrastructure as a Newsletter. New accounts only. By submitting your email you agree to our Privacy Policy Scale up as you grow — whether you're running one virtual machine or ten thousand. Sign up and get $200 in credit for your first 60 days with DigitalOcean.* *This promotional offer applies to new accounts only.