Self-Hosted Container Registry Guide: Images, Access Control, Retention, and Garbage Collection
container registryDockerOCIHarborself-hostingDevOps

Self-Hosted Container Registry Guide: Images, Access Control, Retention, and Garbage Collection

OOpenDev Forge Editorial Team
2026-11-21
8 min read

A practical checklist for running a self-hosted container registry, covering access, storage, retention, garbage collection, backups, and troubleshooting.

A self-hosted container registry gives your team control over where Docker and OCI images are stored, who can use them, and how long they remain available. This guide provides a reusable operating checklist for choosing a registry, configuring secure access, pushing and pulling images, applying retention rules, running garbage collection, testing backups, and troubleshooting routine failures.

Overview

A container registry is the publishing and distribution layer between your build system and the environments that run your software. Developers push images after a build; CI/CD systems pull approved images for testing, staging, and production. A reliable registry therefore needs more than an upload endpoint. It needs durable storage, authentication, project-level permissions, TLS, auditability, capacity controls, and a recovery plan.

Most modern registries support the OCI image format, while Docker-compatible clients remain common. Before selecting a platform, define the features your team actually needs: private projects, robot or deploy credentials, vulnerability scanning, image signing, replication, a web interface, integration with your Git host, and support for object storage or network-attached storage. Treat each feature as a requirement to verify against the version you intend to deploy; registry capabilities and configuration names change over time.

Registry options at a glance

OptionBest fitStrengths to evaluateTrade-offs to check
HarborTeams needing a broader registry platformProject organization, access controls, policy features, and integrationsMore components to operate, secure, monitor, and back up
Docker Distribution RegistryA focused, API-compatible registry serviceSimple core architecture and flexible storage configurationMany team features require surrounding services or additional tooling
GitLab Container RegistryTeams already operating GitLabClose relationship with repositories, pipelines, and project permissionsBest evaluated as part of the wider GitLab deployment and maintenance model
Other open-source registriesSpecialized or lightweight environmentsPotentially different storage, replication, or security modelsConfirm OCI behavior, release activity, documentation, and migration paths

There is no universal winner in a Harbor vs Docker Registry decision. A small team may prefer a focused service with fewer moving parts, while a larger organization may value integrated projects, scanning, replication, and policy controls. Compare operational burden as carefully as feature lists.

Checklist by scenario

1. Before installation

  • Write down image naming conventions, such as registry.example.org/team/application, and decide whether repository names must mirror Git projects.
  • Estimate storage from image size, build frequency, number of platforms, retained releases, and temporary layers. Include room for growth and temporary space used during maintenance.
  • Choose the storage backend and confirm its behavior for large objects, concurrent uploads, permissions, latency, and snapshots.
  • Decide whether the registry will be reachable only inside a private network or exposed through a controlled ingress endpoint.
  • Document the identity source: local accounts, an existing single sign-on provider, directory integration, or machine credentials issued by the platform.
  • Define recovery objectives. A registry backup is useful only if you know how to restore its metadata, configuration, credentials, and image storage together.

2. During initial deployment

  • Use a trusted TLS certificate and configure clients to connect through the intended hostname. Avoid normalizing insecure registry exceptions on developer machines.
  • Separate administrative access from routine image push and pull access. Use project roles and least privilege rather than a shared administrator password.
  • Create dedicated robot, deploy, or CI credentials where supported. Give read-only credentials to deployment environments that do not publish images.
  • Configure persistent storage before the first production push. Test what happens when the storage backend is unavailable or reaches its capacity limit.
  • Enable logs, metrics, and health checks. Monitor failed uploads, authentication errors, request latency, storage consumption, and background jobs.
  • Confirm that the selected registry accepts the image manifests, multi-platform indexes, attestations, and media types produced by your build tools.

3. When onboarding a repository

  • Give the project a clear namespace and decide who may push, pull, delete, or administer images.
  • Configure CI to authenticate without placing long-lived secrets in source code or unprotected build logs.
  • Tag images with an immutable reference, such as a commit identifier or release identifier. Use a moving tag such as latest only as a convenience alias.
  • Build, push, and pull the same image in a test environment before changing a deployment workflow.
  • Record the image digest produced by the build. Deploying by digest prevents a mutable tag from silently pointing to a different artifact.
  • Consider signing release images and attaching an SBOM. See the guide to signing and verifying releases with Sigstore and Cosign and the SBOM generation and review guide.

4. For retention and garbage collection

Retention is a policy decision; garbage collection is the storage cleanup operation that follows it. Deleting a tag may remove a reference without immediately reclaiming every unreferenced layer. The exact behavior depends on the registry, storage driver, and whether uploads or replication jobs are active.

Use a written policy similar to this template, then translate it into the controls your registry actually supports:

Production releases: retain every approved release for the supported rollback window
Development images: retain the newest N images per repository
Pull-request images: retain for a short review period, then remove
Failed and untagged images: remove after verification that no workflow needs them
Release tags: protect from routine deletion
Cleanup schedule: run during a low-traffic maintenance window
Exception process: record repository, reason, owner, and expiry date

Test retention in a non-production project first. Confirm whether rules operate on tags, manifests, repositories, or creation dates. Before garbage collection, check for active uploads, replication tasks, running deployments, and backup jobs. Take a current backup and verify that the registry documents the required read-only or maintenance mode.

5. For backup and replication

  • Back up registry configuration, secrets needed for restoration, metadata, and the image storage backend; backing up only the database is not sufficient.
  • Keep backup credentials separate from registry administrator credentials.
  • Test a restore into an isolated environment. Verify that an image can be authenticated, pulled, and deployed after recovery.
  • If using replication, define which projects move between sites, how conflicts are handled, and which system is authoritative.
  • Measure restore time rather than assuming that a successful backup job meets your recovery needs.

What to double-check

Access control and secrets

Check permissions at every layer: ingress, registry project, repository, storage backend, CI runner, and deployment environment. Rotate credentials on a schedule appropriate to their risk, and revoke unused accounts immediately. A self-hosted CI/CD runner can access more than the registry alone, so review its network path and secret exposure using the self-hosted CI/CD runner guide.

Scanning and supply-chain controls

Vulnerability scanning can be valuable, but it is not a substitute for review of base images, dependency updates, configuration, or runtime behavior. Establish what happens when a scan fails: block publication, mark the image for review, or permit an exception with an owner and expiry. Pair scan results with signed artifacts and SBOM review rather than treating a single status as a complete security decision.

Storage behavior

Verify whether layers are deduplicated, whether deleted content remains until garbage collection, and whether the chosen backend supports the registry’s consistency expectations. Monitor both total capacity and the rate at which capacity is being consumed. If your team also stores large source assets, keep that concern separate from registry sizing; the Git LFS hosting guide covers a different storage workload.

Deployment references

Use immutable image digests in deployment manifests where practical. Keep environment configuration outside the image, and define a rollback image explicitly. The Git deployment guide provides related guidance for environment variables, domains, and rollbacks.

Common mistakes

  • Using one shared account: It prevents meaningful auditing and makes rotation disruptive. Create individual or workload-specific identities.
  • Relying on latest: A mutable tag makes it difficult to prove what was deployed. Pair convenient tags with immutable digests.
  • Deleting tags and assuming storage is free: Confirm how unreferenced layers are reclaimed and schedule garbage collection safely.
  • Running cleanup without a restore test: A policy can delete the only convenient rollback copy. Validate retention and backups before automating deletion.
  • Exposing the registry without TLS: Credentials and image traffic need protected transport. Configure certificates and client trust correctly.
  • Ignoring failed uploads: Repeated retries can leave temporary data or conceal a full disk. Investigate logs, proxy limits, timeouts, and backend capacity.
  • Mixing platform assumptions: Installation commands, scanners, authentication integrations, and garbage-collection procedures are version-specific. Follow the documentation for the deployed release.

Troubleshooting flow

Push fails: confirm DNS and TLS, authenticate again, check project permission, inspect proxy request-size and timeout settings, then check registry and storage logs. If the failure occurs after several layers upload, investigate backend capacity and interrupted upload cleanup.

Credentials are rejected or expired: verify the account or robot token, its scope, clock synchronization, identity-provider status, and whether CI is using a stale secret. Rotate the credential and update the workload through the approved secret-management path.

Disk is filling: identify repositories and untagged content, pause ad hoc deletion, review active uploads and replication, apply the tested retention policy, and run the documented garbage-collection procedure during a safe maintenance window. Expand storage only after confirming that runaway retention or failed cleanup is not the underlying cause.

When to revisit

Review this registry plan at least once per release or monthly operating cycle, and immediately after a registry upgrade, storage migration, authentication change, or major CI/CD workflow change. Recheck supported OCI features, installation steps, authentication integrations, scanner behavior, storage-driver requirements, replication options, and garbage-collection procedures whenever the platform changes.

Use this short operational review:

  • Compare current storage growth with the estimate and confirm the next expansion threshold.
  • Sample project permissions and remove unused accounts, tokens, and repositories.
  • Review retention exceptions, protected release tags, and untagged-image volume.
  • Test one pull by digest and one rollback from a retained image.
  • Check backup completion, restore evidence, and recovery documentation.
  • Review scan, signing, and SBOM workflows after build tooling changes.
  • Update the runbook with the deployed registry version and its verified maintenance commands.

Finally, link registry ownership to the wider hosting and recovery plan. Review the self-hosted Git backup and disaster recovery guide, the license compliance workflow, and the CI/CD rollback and incident response playbook when those systems share deployment responsibilities.

Related Topics

#container registry#Docker#OCI#Harbor#self-hosting#DevOps
O

OpenDev Forge Editorial Team

Open-Source Infrastructure Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.