Halloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsSlow PC?RecommendedPC slow today? Run a repair scan before it gets worseResolve common Windows issues and optimize system performance.Scan NowHalloween DealsAmazon USOctober picks are moving - compare before checkoutAmazon US: current deals, useful picks and tech finds.See Picks×
FREEDOM251

Freedom251 › Blog › CNCF Distribution

How to Set Up a Private Docker Registry on a VPS

By Freedom251 Team · · 11 min read

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The reliable pattern is straightforward: run the CNCF Distribution registry in Docker on a VPS, persist its storage, give it a DNS name, protect external access with trusted HTTPS, configure authentication, and test push and pull from another Docker client. The short docker run example often shown in documentation is useful for a local trial, but it is not a production configuration until TLS, access control, backups, and retention procedures are in place.

What a private registry on a VPS actually is

A Docker registry is a service that stores image manifests and layer blobs and serves them through the Docker Registry HTTP API. In this design, the registry software runs as a container on your VPS. The VPS supplies compute, networking, a public address, and disk; it does not automatically provide image storage, authentication, backups, or a secure endpoint.

As an Amazon Associate I earn from qualifying purchases.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The CNCF Distribution project publishes the registry image used for this setup. Its current deployment example uses registry:3. Distribution documentation describes TLS and basic authentication as native capabilities and states that a production-ready registry must be protected by TLS and should ideally use an access-control mechanism.

A complete deployment therefore has these moving parts:

#1 Best Overall
Sale
TOZO A1 Wireless Earbuds Bluetooth 5.3 Light Weight in Ear Headphones | IPX5 Waterproof,2 Mics for AI Calls,Immersive Premium Sound Bass Headset with Charging Case,32 EQ via App Black
  • [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
  • [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
  • [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
  • [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
  • [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.
  • A VPS with Docker already installed and enough persistent disk for the images you intend to retain.
  • A DNS name such as registry.example.com pointing to the VPS.
  • Firewall and routing rules that permit only the traffic you intend to serve, normally HTTPS on port 443.
  • Distribution registry configuration with a persistent storage root.
  • A trusted certificate and private key, either configured directly in the registry or supplied by a reverse proxy.
  • Authentication and repository permissions tested from a Docker client.
  • Backups and a documented deletion and garbage-collection procedure.

Plan the VPS, DNS, and network first

Choose persistent capacity, not just CPU

Image size, the number of tags, concurrent uploads, retention policy, and backup history determine capacity. The official material does not prescribe a universal VPS size or throughput figure; those values vary with your workload. Start by measuring the compressed size of the images you actually publish and reserve room for multiple versions, temporary upload data, logs, and local backup staging.

Do not place the registry’s only copy on an ephemeral disk. If the VPS provider offers an attached block volume, mount it at a stable host path such as /srv/registry. Keep that path in your backup plan. The registry’s default local POSIX filesystem is suitable for development and small deployments, while the project also documents S3, Microsoft Azure, and Google Cloud Storage backends when you want image data separated from the VPS.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Create a dedicated hostname

Create an A or AAAA record for a name dedicated to the registry, for example registry.example.com. Use the same hostname when obtaining the certificate, configuring the registry or proxy, logging in, and tagging images. A mismatch between the name in the certificate and the name in an image tag is a common cause of failed pushes.

Restrict exposure

The registry process normally listens on port 5000 internally. For an externally accessible service, expose HTTPS on port 443 and keep the backend port private whenever possible. Open SSH only to the administration sources you need, and avoid publishing an unauthenticated registry directly to the internet.

Install Docker and prepare storage

Install Docker using the instructions for your VPS operating system, then confirm that the daemon and client work:

docker version

Create the host directory that will hold registry data and ensure the Docker daemon can write to it:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
sudo mkdir -p /srv/registry
sudo chown -R root:root /srv/registry

The exact ownership and labeling requirements depend on the operating system’s security policy. The important design requirement is that the path is on persistent storage and is included in backups. If you use an object-storage backend instead, keep its bucket or container credentials outside the image and treat that service as part of the registry’s durability design.

Run a bootstrap registry container

The minimal command documented by Distribution is:

docker run -d -p 5000:5000 --restart=always --name registry registry:3

This starts a registry for a quick local test. It does not configure persistent host storage, HTTPS, or authentication, so do not use it as the final public deployment.

Rank #2
Sale
Smart Watch for Men Women Compatible with iPhone Samsung Android Phone 1.69 inch Full Touch Screen IP68 Waterproof Bluetooh Fitness Tracker Heart Rate/Sleep Monitor (Black)
  • 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
  • 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
  • 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
  • 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
  • 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.

A useful bootstrap command with a persistent local filesystem is:

docker run -d 
  --name registry 
  --restart=always 
  -p 5000:5000 
  -v /srv/registry:/var/lib/registry 
  registry:3

Check that the container is running and inspect its logs before adding the public endpoint:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
docker ps --filter name=registry
docker logs --tail=100 registry

At this point, treat the service as a private development endpoint. Distribution’s own deployment guidance labels unsecured examples as testing-only until TLS and access control are added.

Configure storage deliberately

Local filesystem storage

Local storage is the simplest choice for a small registry. Set the filesystem root explicitly when mounting a host path so that the container’s /var/lib/registry corresponds to the disk you planned. A configuration file can make that choice explicit:

version: 0.1
storage:
filesystem:
rootdirectory: /var/lib/registry

If you supply a complete configuration file, mount it read-only and start the container with the registry’s configuration path. Keep the data directory and configuration backups separate: the data contains image content, while the configuration contains endpoint, authentication, and storage settings.

Object-storage backends

Distribution documents backends for S3, Microsoft Azure, and Google Cloud Storage. Object storage can separate image data from the VPS, simplify capacity growth, and make a replacement VPS less disruptive. It also introduces provider credentials, bucket policy, network latency, and a second service whose availability and cost must be managed. Compare the options on durability and backup design, capacity growth, operational complexity, latency, portability, and cost rather than assuming one is universally better.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Storage choice Strengths Operational concerns
Local POSIX filesystem Simple deployment and low request latency for a small registry VPS disk capacity and failure domain; backups must copy the registry data elsewhere
S3, Microsoft Azure, or Google Cloud Storage backend Image data can be separated from the VPS and expanded independently Credentials, bucket or container policy, provider availability, latency, and usage charges

Secure the registry with HTTPS

Distribution’s deployment documentation says that external access requires TLS. Use a certificate issued by a publicly trusted certificate authority for clients that are not centrally managed. A self-signed certificate can be useful in a controlled test environment, but every Docker client must then trust your private CA, and an unverified self-signed setup is not an acceptable public configuration.

Terminate TLS in the registry

The registry can serve HTTPS itself. The relevant settings are the certificate and private-key paths under the HTTP configuration. A minimal configuration fragment looks like this:

Rank #3
New Bee Guitar Cable 10ft Electric Instrument Bass AMP Cord
  • [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
  • [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
  • [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
  • [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
  • [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by
http:
addr: :5000
tls:
certificate: /certs/registry.crt
key: /certs/registry.key

Mount the certificate directory into the container without making the private key world-readable. Keep the key out of image layers and source repositories. If you use Let’s Encrypt integration as described in the Distribution documentation, the outward-facing address must be reachable on port 443 and the allowed host list should be constrained to the registry hostname.

Terminate TLS at a reverse proxy

A separate web server can proxy HTTPS to the registry’s private port 5000. This is useful when the VPS already has a reverse proxy that automates certificates, centralizes access logs, or applies network-level policy. The proxy must preserve the Docker Registry API’s request and response behavior, allow large uploads, and pass authentication challenges correctly. Keep port 5000 bound to localhost or an internal network instead of exposing it directly.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Design When it fits Trade-offs
TLS in Distribution The registry is the only HTTPS service or you want its certificate settings managed with the registry Certificate renewal and HTTPS logging are tied to the registry container’s configuration
TLS at a reverse proxy The VPS already standardizes certificate automation, logging, and front-door access control There is an additional proxy failure point and it must be configured for registry uploads and authentication

Whichever design you choose, verify the public hostname with a separate Docker client. A browser test alone does not prove that the Docker Registry API, certificate chain, and upload handling are correct.

Add authentication and repository authorization

Distribution natively supports TLS and basic authentication. Docker clients normally receive an authentication challenge and then obtain a repository-scoped bearer token. A container starting successfully does not prove that credentials, token scope, or repository permissions are correct.

Use a protected credential store

Configure the registry’s authentication section with a realm and a credential source such as an htpasswd file, then mount that file into the container read-only. Keep the realm URL consistent with the externally visible HTTPS endpoint. The exact command used to create the password file depends on the operating system’s Apache utilities, but the resulting file must be readable by the registry process and must not be stored in the image itself.

For multiple teams or fine-grained permissions, place an authorization service in front of Distribution or use a token service that issues repository-scoped bearer tokens. Basic authentication alone identifies a user; it does not automatically express which repositories that user may push to.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Test the challenge from a client

From a workstation or CI runner that is not the VPS, log in to the registry hostname:

docker login registry.example.com

Enter the credentials for the account you intend to use. Test both an allowed repository and a denied operation. A successful login followed by an unauthorized push usually indicates a token-scope or repository-policy problem, not a Docker daemon problem.

Rank #4
BSIMB 15.6" Digital Family Calendar & Chore Chart, No Subscription Fees
  • Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
  • Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
  • All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
  • Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
  • Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Push and pull a test image end to end

This workflow checks DNS, certificate trust, authentication, storage writes, and client compatibility in one pass.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  1. Pull a small public image that your client can access:
    docker pull alpine:latest
  2. Retag it with your registry hostname and a repository name:
    docker tag alpine:latest registry.example.com/test/alpine:latest
  3. Authenticate to the registry:
    docker login registry.example.com
  4. Push the tag:
    docker push registry.example.com/test/alpine:latest
  5. Remove the local copies so the next pull is meaningful:
    docker image rm alpine:latest registry.example.com/test/alpine:latest
  6. Pull the image from the private registry:
    docker pull registry.example.com/test/alpine:latest

If the push fails, read the client error and the registry or proxy logs together. Certificate errors point to hostname or trust-chain problems; 401 Unauthorized indicates an authentication challenge or missing credentials; 403 Forbidden commonly indicates a repository-scope decision; and storage errors require checking the mounted path, disk availability, and backend credentials.

Back up and monitor the data

A registry backup is more than a copy of the container definition. For local storage, back up the entire configured filesystem root while the registry is in a consistent state, and preserve the registry configuration and authentication files separately. For object storage, back up or replicate the bucket or container according to that provider’s durability and versioning features, and retain the credentials and policy needed to restore access.

Test restoration on a separate Docker host. A backup that cannot be used to start a registry and pull a known tag is not a verified backup. Monitor disk usage, failed uploads, authentication failures, certificate expiry, and registry container restarts.

Delete old images safely

Deletion is disabled by default in the Distribution configuration reference. That default prevents an accidental API call from removing manifests. If you need retention cleanup, enable deletion deliberately and document which repositories and tags are eligible.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Understand tags, manifests, and blobs

A tag points to a manifest. The manifest references layer blobs, and layers may be shared by many tags or repositories. Removing a tag or manifest does not necessarily free disk space immediately because shared or unreferenced blobs remain until garbage collection determines that nothing references them.

Use a read-only window

Before garbage collection, stop writes or run the registry in read-only mode. New pushes that arrive while the mark-and-sweep process is evaluating manifests can create races or leave storage in an unexpected state. Schedule the operation during a maintenance window and ensure that CI jobs cannot push during it.

Perform a dry run, then collect

Run the Distribution garbage-collection command in dry-run mode first and review the blobs it would remove. After confirming that the result matches your retention policy, run collection for real. The --delete-untagged option removes untagged manifests; use it only when those manifests are intentionally disposable.

docker exec registry registry garbage-collect --dry-run /etc/distribution/config.yml
docker exec registry registry garbage-collect --delete-untagged /etc/distribution/config.yml

The exact configuration-file path must match the path used by your container. Keep a current backup before the destructive run. If you cannot stop writes, defer collection rather than gambling with active uploads.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Common failure modes and fixes

“HTTP response to HTTPS client” or insecure-registry errors

The client is contacting a registry that is speaking plain HTTP, or a proxy is forwarding to the wrong endpoint. Use the certificate-backed hostname and expose HTTPS on port 443. Do not solve a public deployment by adding an insecure-registry exception to every Docker daemon.

Certificate is valid for a different name

Retag and log in with the hostname covered by the certificate. Check DNS and certificate renewal if the name changed. A certificate for the VPS’s provider hostname does not automatically cover registry.example.com.

Login succeeds but push is denied

Inspect the repository name and the token scope returned after the challenge. Confirm that the account is authorized to push to that repository and that the reverse proxy is forwarding authentication headers and status codes unchanged.

Pushes fail part way through

Check free disk space, the mounted filesystem root, proxy upload limits, and network timeouts. For object storage, verify bucket or container credentials and policy. Review both the Docker client output and registry logs; one often identifies whether the failure occurred before or after a blob reached storage.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Garbage collection removes less than expected

Shared blobs remain while any manifest references them. Remove the intended manifests or tags first, wait for the retention policy to take effect, then run garbage collection during a read-only window. A dry run shows what the collector considers unreferenced.

Production readiness checklist

  • Registry data is on persistent storage, not the container’s writable layer.
  • The registry hostname resolves correctly from every intended client network.
  • Port 443 is reachable; the backend port 5000 is not unnecessarily public.
  • A trusted certificate covers the exact hostname clients use.
  • Authentication is enabled and repository permissions have been tested with a real Docker client.
  • Configuration, credentials, and image data are backed up with a tested restore procedure.
  • Disk, certificate, authentication, upload, and restart conditions are monitored.
  • Deletion remains disabled unless a retention policy requires it.
  • Garbage collection is preceded by a backup, read-only period, and dry run.

Final deployment sequence

For a small, self-managed service, the safest order is to prepare the VPS and persistent disk, point DNS at the host, run Distribution with a persistent volume, configure HTTPS, add authentication, and complete the push-remove-pull test from another machine. Only after those checks pass should the registry become a dependency for CI or production deployments. Choose local storage when simplicity and a small footprint matter; choose an object-storage backend when separating image data from the VPS and expanding capacity are more important. In both cases, secure the endpoint first and treat retention and recovery as part of the registry, not as optional housekeeping.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

CNCF Distributioncontainer securityDevOpsDockerPrivate registryVPS

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
Crashes, No Sound, or Screen Glitches?Free driver scan
PC Slower Than It Used to Be?Free scan - under a minute

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.