{
  "manifest_version": "1",
  "slug": "container-registry",
  "title": "Docker Registry",
  "headline": "Self-host a private Docker registry",
  "description": "Run a private Docker and OCI registry on an exe.dev VM: docker login with an exe.dev token, push from laptops and CI, pull from your VMs and k3s, and cache Docker Hub.",
  "category": "dev-tools",
  "tags": [
    "private docker registry",
    "container registry",
    "oci registry",
    "self-hosted registry",
    "docker distribution",
    "registry:3",
    "zot",
    "pull-through cache",
    "docker hub mirror",
    "docker hub rate limit"
  ],
  "url": "https://exe.dev/deploy/container-registry",
  "markdown_url": "https://exe-staging.dev/deploy/container-registry.md",
  "upstream": {
    "website": "https://distribution.github.io/distribution/",
    "source": "https://github.com/distribution/distribution",
    "docs": "https://distribution.github.io/distribution/about/configuration/",
    "license": "Apache-2.0"
  },
  "example_vm_name": "my-registry",
  "time": "10 minutes",
  "stack": [
    {
      "name": "Distribution 3.1",
      "detail": "the registry:3.1.2 image in Docker Compose, with no auth of its own",
      "port": 8000,
      "data": "~/registry/data"
    },
    {
      "name": "Docker Registry UI 2.6",
      "detail": "joxit/docker-registry-ui, for browsing and deleting tags",
      "port": 8001
    },
    {
      "name": "Garbage collection",
      "detail": "a weekly systemd timer that frees the space of deleted tags"
    }
  ],
  "access": [
    {
      "url": "https://my-registry.exe.xyz/",
      "who": "private",
      "what": "The registry, for you, people you share the VM with, and exe.dev tokens for this VM"
    },
    {
      "url": "https://my-registry.exe.xyz:8001/",
      "who": "private",
      "what": "The web UI"
    }
  ],
  "delivers": [
    "Distribution 3.1 on port 8000, private behind exe.dev login, restarted at boot",
    "A web UI on port 8001 for browsing and deleting tags",
    "Weekly garbage collection that frees the space of deleted tags",
    "A test image pushed, pulled and deleted again on the VM itself"
  ],
  "deployable": true,
  "deploy": {
    "new_vm_url": "https://exe-staging.dev/new?prompt=Set%20up%20Docker%20Registry%20on%20this%20VM%20by%20following%20the%20exe.dev%20recipe%20at%20https%3A%2F%2Fexe-staging.dev%2Fdeploy%2Fcontainer-registry.md%3Fvia%3Ddeploy%20from%20top%20to%20bottom.%0A%0AThe%20recipe%27s%20example%20VM%20name%20is%20my-registry.%20This%20VM%27s%20name%20is%20the%20output%20of%20%60hostname%60%3A%20use%20it%20wherever%20the%20recipe%20writes%20my-registry.%20Skip%20the%20step%20that%20creates%20the%20VM%3B%20you%20are%20on%20it.%0A%0AYou%20are%20done%20when%20all%20of%20these%20are%20true.%20Check%20each%20one%20yourself%3A%0A-%20Distribution%203.1%20on%20port%208000%2C%20private%20behind%20exe.dev%20login%2C%20restarted%20at%20boot%0A-%20A%20web%20UI%20on%20port%208001%20for%20browsing%20and%20deleting%20tags%0A-%20Weekly%20garbage%20collection%20that%20frees%20the%20space%20of%20deleted%20tags%0A-%20A%20test%20image%20pushed%2C%20pulled%20and%20deleted%20again%20on%20the%20VM%20itself%0A%0ARead%20the%20whole%20recipe%2C%20then%20run%20only%20%22Install%20by%20hand%22%2C%20skipping%20VM%0Acreation.%20Tokens%2C%20other%20machines%2C%20GitHub%20Actions%2C%20the%20Docker%20Hub%20cache%0Aand%20zot%20are%20the%20owner%27s%20choice%20afterwards%3B%20don%27t%20set%20those%20up%20unless%0Aasked.%20You%20can%27t%20create%20tokens%20from%20the%20VM%3A%20they%20need%20the%20owner%27s%0A%60ssh%20exe.dev%60.%20Verify%3A%20docker.service%20is%20enabled%3B%20%60docker%20compose%20ps%60%0Ain%20~%2Fregistry%20shows%20registry%20and%20ui%20running%3B%20the%20smoke%20test%20in%0A%22Check%20it%22%20passes%3B%20registry-gc.timer%20is%20enabled.%20Finish%20with%20the%20UI%20URL%0A%28port%208001%29%20and%20the%20commands%20for%20the%20owner%27s%20computer%20from%20%22Push%20your%0Afirst%20image%22%2C%20with%20this%20VM%27s%20name.%0A%0AFinish%20with%20the%20URLs%20I%20should%20open.%0A",
    "terminal": "curl -fsSL https://exe-staging.dev/deploy/container-registry/prompt.txt | ssh exe.dev new --prompt=/dev/stdin",
    "prompt": "Set up Docker Registry on this VM by following the exe.dev recipe at https://exe-staging.dev/deploy/container-registry.md?via=deploy from top to bottom.\n\nThe recipe's example VM name is my-registry. This VM's name is the output of `hostname`: use it wherever the recipe writes my-registry. Skip the step that creates the VM; you are on it.\n\nYou are done when all of these are true. Check each one yourself:\n- Distribution 3.1 on port 8000, private behind exe.dev login, restarted at boot\n- A web UI on port 8001 for browsing and deleting tags\n- Weekly garbage collection that frees the space of deleted tags\n- A test image pushed, pulled and deleted again on the VM itself\n\nRead the whole recipe, then run only \"Install by hand\", skipping VM\ncreation. Tokens, other machines, GitHub Actions, the Docker Hub cache\nand zot are the owner's choice afterwards; don't set those up unless\nasked. You can't create tokens from the VM: they need the owner's\n`ssh exe.dev`. Verify: docker.service is enabled; `docker compose ps`\nin ~/registry shows registry and ui running; the smoke test in\n\"Check it\" passes; registry-gc.timer is enabled. Finish with the UI URL\n(port 8001) and the commands for the owner's computer from \"Push your\nfirst image\", with this VM's name.\n\nFinish with the URLs I should open.\n",
    "prompt_url": "https://exe-staging.dev/deploy/container-registry/prompt.txt"
  },
  "published": "2026-11-21",
  "updated": "2026-11-21",
  "verified": "2026-11-21",
  "related": [
    "docker-builder",
    "docker-host",
    "github-actions",
    "k3s",
    "docker-compose",
    "dev-test-prod"
  ],
  "alternatives": [
    "Docker Hub",
    "GitHub Container Registry",
    "Amazon ECR"
  ]
}
