What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
You can run a private Docker registry on a VPS with the official registry:3 image, a DNS name, durable storage, HTTPS, and authentication. The registry stores image layers on the VPS (or in an object-storage backend), while Docker clients push and pull through a hostname such as myregistry.domain.com.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
The reliable production pattern is to keep the registry process on an internal port, terminate trusted TLS on the registry or a reverse proxy, require authenticated access, restrict the firewall, and back up both image data and configuration. The one-line container command is useful for a quick test, but its defaults are not suitable for an internet-facing service.
As an Amazon Associate I earn from qualifying purchases.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →What a private Docker registry on a VPS actually does
A registry is an HTTP API that accepts image layers and manifests from Docker clients and serves them back when a client pulls an image. CNCF Distribution packages that service as the registry image; using the registry:3 tag gives you the current major-version image used in the deployment examples.
The VPS supplies the network endpoint, firewall, CPU, memory, and storage. DNS maps a name such as myregistry.domain.com to the VPS address. Clients then address images with that hostname, for example myregistry.domain.com/my-ubuntu, instead of using a public registry.
#1 Best Overall
A minimal architecture has four layers:
- Docker Registry container: the Distribution service that implements the registry API.
- Persistent data: a mounted VPS directory or an object-storage bucket containing blobs and manifests.
- HTTPS endpoint: TLS handled by Distribution itself or by a reverse proxy in front of it.
- Authorization: basic authentication for a small installation or a bearer-token service with repository-scoped permissions for larger teams.
Docker clients normally contact the registry, receive an authentication challenge, obtain a bearer token from the configured authorization service, and retry the original operation with that token. This challenge-and-token sequence is why authentication is more than putting a password prompt in front of a web page.
Requirements and decisions to make before deployment
DNS and public routing
Create a DNS record for the registry hostname and point it to the VPS. The name must resolve from every network that will push or pull images. Public clients need a route to TCP port 443. If the registry is only for an isolated private network, keep the endpoint private and use that network’s DNS and firewall rules instead.
Recommended Free Tools
A Docker-capable VPS
Install Docker Engine on a supported host operating system and ensure you can administer the server. The sources do not establish a universal VPS size or image-capacity limit. Choose CPU, memory, disk, and network capacity from your repository count, layer sizes, concurrent pushes and pulls, and backup window rather than from a generic “small VPS” label.
Durable storage
Decide whether image data belongs on a persistent POSIX filesystem attached to the VPS or in object storage. Distribution supports its local filesystem driver as well as S3, Microsoft Azure, and Google Cloud Storage drivers. A local filesystem is straightforward for a small deployment; object storage can separate registry data from the VPS disk and provide a different durability and expansion model.
Firewall and administration access
Allow only the ports you need. In a typical public deployment that means SSH (ideally restricted to administrator addresses) and HTTPS on port 443. Do not expose the registry’s unencrypted internal port to the internet. If a reverse proxy is used, bind the registry to localhost or a private interface and expose only the proxy.
Certificate and identity plan
Internet-facing clients should receive a certificate issued by a trusted certificate authority. Distribution’s documentation also describes automatic certificates through Let’s Encrypt. Reserve plain HTTP and untrusted self-signed certificates for controlled testing; ordinary Docker clients will reject an untrusted endpoint unless each client is deliberately configured to treat it as insecure.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsRun a disposable registry to verify Docker and networking
Before adding TLS and credentials, verify that the VPS can run the image and that Docker can reach the service locally:
docker run -d -p 5000:5000 --restart=always --name registry registry:3This starts Distribution on port 5000 and restarts the container after a Docker or host restart. It is a connectivity test, not a production configuration: the command does not configure HTTPS, authentication, a durable host mount, a reverse proxy, or a retention and backup plan.
For a local-only test, tag and push an image to the published port:
docker pull ubuntu:16.04
docker tag ubuntu:16.04 localhost:5000/my-ubuntu
docker push localhost:5000/my-ubuntu
docker pull localhost:5000/my-ubuntuUse docker ps to confirm that the container is running and docker logs registry to inspect startup or push errors. Remove the test container before the production deployment so an unauthenticated service is not left listening:
docker rm -f registryChoose where TLS terminates
There are two sound layouts. The choice changes certificate management and proxy configuration, not the registry API that clients use.
| Layout | How it works | When it fits | Important consideration |
|---|---|---|---|
| TLS in Distribution | The registry process listens on HTTPS and reads a certificate and private key from mounted files. | A single-purpose VPS with no existing web server. | Set REGISTRY_HTTP_TLS_CERTIFICATE and REGISTRY_HTTP_TLS_KEY; publish the HTTPS listener on port 443. |
| TLS at a reverse proxy | The proxy owns the public certificate and forwards requests to the registry’s internal HTTP port. | A host that already serves websites or centralizes certificate renewal. | Keep the registry port private and configure the proxy to preserve the registry request path and headers. |
Distribution’s configuration reference allows TLS to be placed on an existing web server instead of inside the registry. In either layout, clients should use the same https://myregistry.domain.com/ hostname and a certificate whose name matches that hostname.
Terminate TLS inside the registry
Place the certificate and private key in a directory readable by the container but not by unrelated users. Mount that directory read-only, set the two TLS environment variables, and publish the HTTPS listener on 443. A conceptual container invocation is:
docker run -d
--name registry
--restart=always
-p 443:5000
-v /srv/registry/data:/var/lib/registry
-v /srv/registry/certs:/certs:ro
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/fullchain.pem
-e REGISTRY_HTTP_TLS_KEY=/certs/privkey.pem
registry:3The exact certificate filenames can differ, but the certificate chain and key must be present at the paths supplied to the container. Renew the certificate before expiry and restart or reload the service according to the way your certificate process updates the files.
Free tools Windows power users keep installed
One-click scans. No signup required.
Terminate TLS at a reverse proxy
Bind Distribution to a loopback or private address, for example 127.0.0.1:5000, and configure the proxy to listen on 443. The proxy obtains and renews the trusted certificate, then forwards registry API requests to the internal listener. This arrangement avoids publishing an unencrypted registry port and lets one proxy handle certificates for several services.
Do not accidentally proxy only a browser landing page or strip request methods. Registry clients use methods such as GET, HEAD, POST, PATCH, and PUT while uploading layers and manifests, so the proxy must pass those requests, response codes, and authentication headers through unchanged.
Make image data persistent
Local filesystem storage
The default local POSIX filesystem driver is suitable for development and many small installations. Mount a host directory at the registry’s data path so that replacing the container does not delete images. Distribution exposes the path as REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY; the equivalent YAML setting is storage.filesystem.rootdirectory.
mkdir -p /srv/registry/data
chown -R root:root /srv/registry/dataThe ownership and permission details must match the user under which your container and host security policy run. The key requirement is that the registry can read and write the mounted directory and that unprivileged users cannot browse private image data directly on the host.
Object-storage backends
Distribution also supports S3, Microsoft Azure, and Google Cloud Storage drivers. Select an object-storage backend when you want image blobs outside the VPS filesystem or need storage managed independently of the compute host. Keep credentials outside the image and restrict them to the bucket or container operations the registry requires.
Changing the backend is an operational migration, not merely a different mount point. Plan how existing blobs and manifests will be copied, how configuration will change, and how you will verify pulls before deleting the old data.
Back up more than the blobs
Back up the registry data and the material needed to recreate the service: registry configuration, TLS renewal data, authentication files or token-service configuration, and the backup procedure itself. A copy of image layers without the credentials or configuration may not be usable after a rebuild. Test restoration by starting a separate registry instance and pulling a known image.
Add authentication and authorization
Basic authentication for a small team
Distribution natively supports basic authentication. Its htpasswd authentication scheme must be used with TLS; sending basic credentials over plain HTTP would expose them. Store the password file outside the image, mount it read-only, and grant accounts only to people who need registry access.
Basic authentication is simple when a few users share the same trust boundary, but it does not by itself provide repository-level permissions or a convenient way to issue short-lived credentials. Rotate the password file when staff or automation changes and treat it as a secret in backups.
Bearer-token authorization for multiple repositories
The documented token flow is:
- The client attempts an operation such as pulling a manifest or pushing a layer.
- The registry returns
401 Unauthorizedwith aWWW-Authenticatechallenge. - The client contacts the authorization service named by that challenge and requests a token.
- The authorization service returns a token containing the permitted repository actions.
- The client retries the original operation with the bearer token.
Use a token authorization service when several teams, automation accounts, or repositories need different permissions. Scope tokens to the repository and action required, such as pull-only access for a deployment host and push access for a build system. Avoid sharing one all-powerful password across every client.
Keep credentials out of image layers
Log in from each client with Docker’s credential workflow and use a credential store where available. Never put registry passwords in a Dockerfile, a command committed to source control, or an image layer. If a credential appears in a shell history or build log, revoke or rotate it.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Publish and retrieve an image
Once DNS, trusted HTTPS, and authentication are working, the standard workflow is to tag an existing image with the registry hostname:
docker pull ubuntu:16.04
docker tag ubuntu:16.04 myregistry.domain.com/my-ubuntu
docker push myregistry.domain.com/my-ubuntu
docker pull myregistry.domain.com/my-ubuntuThe repository name after the hostname is part of the registry namespace. Keep naming conventions predictable, for example team/service, and use immutable version tags in deployment automation even if developers also publish a moving tag such as latest.
After a successful push, verify from a second client or network. A pull that succeeds only on the VPS can hide DNS, firewall, certificate-chain, or authentication problems affecting real users.
Lock down the VPS
- Firewall: expose 443 for registry traffic and restrict administration ports. Do not publish port 5000 publicly when a proxy or HTTPS listener is in use.
- Trusted certificates: use a certificate authority-issued certificate for internet-facing access. Keep self-signed certificates to isolated testing and configure every test client explicitly if you use them.
- Least privilege: give repositories and automation accounts only the pull or push rights they need.
- Host updates: update Docker Engine, the host operating system, the registry image, and reverse-proxy packages on a planned schedule.
- Secret handling: protect private keys, password files, token-service keys, and object-storage credentials with restrictive permissions and encrypted backups.
- Monitoring: watch container health, certificate expiry, failed authentication, upload errors, and disk or object-storage growth.
Plan capacity, retention, and garbage collection
No authoritative source establishes a universal image-capacity, bandwidth, or VPS-sizing number. Measure the actual inputs: total compressed layer size, number of repositories, upload and download concurrency, build frequency, and the amount of history your teams must retain.
Tags can move while old layers remain referenced by other manifests. Establish a retention policy before the disk fills, such as keeping release tags and deleting superseded development tags according to your team’s needs. The reviewed configuration material does not publish a universal retention schedule, so choose one deliberately and document who approves deletion.
Garbage collection must be treated as a maintenance operation. Schedule it only after confirming that unwanted manifests and tags have been removed, keep a backup, and perform the operation during a window in which pushes are controlled. Monitor free space afterward rather than assuming that deleting a tag immediately returns all layer space.
Common failure modes and fixes
| Symptom | Likely cause | What to check |
|---|---|---|
401 Unauthorized on push or pull |
Credentials are missing, expired, or lack repository permission. | Inspect the WWW-Authenticate challenge, log in to the exact hostname, and verify the account’s repository scope. |
| Certificate or x509 error | The certificate is expired, issued for another name, incomplete, or not trusted by the client. | Confirm that the client uses myregistry.domain.com, renew the certificate, and serve the complete trusted chain. |
| Connection refused on 443 | The proxy or registry is stopped, the firewall blocks the port, or DNS points elsewhere. | Check container status and logs, listener bindings, firewall rules, and DNS resolution from the client network. |
| Push succeeds, but images vanish after recreation | The registry data directory was not mounted to durable storage. | Inspect the container mounts and confirm that /var/lib/registry maps to the intended host path or object-storage backend. |
| Uploads fail partway through | A proxy timeout, request-size rule, unstable network, or full storage interrupts the upload. | Review proxy timeouts and request handling, registry logs, available disk or object-storage quota, and client connectivity. |
| HTTP works locally but not from the internet | The service is bound only to loopback, DNS is wrong, or the VPS firewall blocks external traffic. | Test DNS and TCP 443 from an external network and verify the proxy’s public listener. |
Operational checklist for a production registry
- Point the registry DNS name at the VPS and verify that it resolves from client networks.
- Create durable storage and confirm the registry can write to it.
- Run Distribution behind HTTPS, either directly with
REGISTRY_HTTP_TLS_CERTIFICATEandREGISTRY_HTTP_TLS_KEYor through a reverse proxy. - Configure authentication; use TLS whenever the
htpasswdscheme is enabled. - Restrict the firewall to required administration and HTTPS traffic.
- Push and pull a test image from a separate client.
- Back up image data, configuration, certificates, and credential material.
- Monitor storage growth, certificate expiry, authentication failures, and registry logs.
- Document retention and garbage-collection procedures before storage pressure becomes urgent.
- Keep the registry, Docker Engine, operating system, and proxy updated.
Which deployment option fits?
| Decision | Simpler choice | More scalable or flexible choice |
|---|---|---|
| TLS termination | Distribution handles TLS directly. | A reverse proxy centralizes certificates and serves other applications. |
| Authentication | Basic authentication for a small, trusted group. | Bearer-token authorization with repository-scoped permissions. |
| Storage | Mounted local POSIX filesystem on the VPS. | S3, Microsoft Azure, or Google Cloud Storage backend. |
| Infrastructure | One VPS containing registry and data. | Registry compute separated from externally managed object storage and backup systems. |
A single VPS is attractive because it is easy to understand and inexpensive to operate, but it concentrates compute, network endpoint, and local disk in one failure domain. External storage reduces that coupling but adds credentials, backend configuration, and migration considerations. Select the simplest arrangement that satisfies your recovery, access-control, and availability requirements.
Quick Recap
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.
