{"id":13547139,"url":"https://github.com/ahmetb/serverless-registry-proxy","last_synced_at":"2025-10-10T14:39:57.334Z","repository":{"id":38845482,"uuid":"180426303","full_name":"ahmetb/serverless-registry-proxy","owner":"ahmetb","description":"Serverless reverse proxy for exposing container registries (GCR, Docker Hub, Artifact Registry etc) on custom domains.","archived":false,"fork":false,"pushed_at":"2023-12-27T12:47:18.000Z","size":66,"stargazers_count":264,"open_issues_count":7,"forks_count":60,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-05T03:02:24.514Z","etag":null,"topics":["artifact-registry","cloud-run","docker-hub","gcr","gcr-registry","google-artifact-registry","google-cloud-run"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ahmetb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-04-09T18:26:43.000Z","updated_at":"2025-02-17T17:12:04.000Z","dependencies_parsed_at":"2024-01-12T20:03:40.936Z","dependency_job_id":null,"html_url":"https://github.com/ahmetb/serverless-registry-proxy","commit_stats":null,"previous_names":["ahmetb/gcr-custom-domains"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmetb%2Fserverless-registry-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmetb%2Fserverless-registry-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmetb%2Fserverless-registry-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmetb%2Fserverless-registry-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ahmetb","download_url":"https://codeload.github.com/ahmetb/serverless-registry-proxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247492565,"owners_count":20947545,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artifact-registry","cloud-run","docker-hub","gcr","gcr-registry","google-artifact-registry","google-cloud-run"],"created_at":"2024-08-01T12:00:51.507Z","updated_at":"2025-10-10T14:39:52.280Z","avatar_url":"https://github.com/ahmetb.png","language":"Go","funding_links":[],"categories":["Go","Tools"],"sub_categories":[],"readme":"# Serverless Container Registry Proxy\n\nThis project offers a very simple reverse proxy that lets you expose your public\nor private Docker registries (such as [Google Container\nRegistry](https://cloud.google.com/container-registry) `gcr.io`, [Google\nArtifact Registry](https://cloud.google.com/artifact-registry) (`*.pkg.dev`) or\nDocker Hub account) as a public registry on your own domain name.\n\nYou can also fork this project and customize as a middleware and deploy to\n[Cloud Run][run] or somewhere else since it’s a generic docker registry proxy.\n\n[![Run on Google Cloud](https://storage.googleapis.com/cloudrun/button.png)](https://console.cloud.google.com/cloudshell/editor?shellonly=true\u0026cloudshell_image=gcr.io/cloudrun/button\u0026cloudshell_git_repo=https://github.com/ahmetb/serverless-registry-proxy)\n\nFor example, if you have a public registry, and offering images publicly with\nnames such as:\n\n    docker pull gcr.io/ahmetb-public/foo\n    # or\n    docker pull us-central1-docker.pkg.dev/ahmetb-demo/ahmetb-demo/foo\n\nyou can use this proxy, and instead offer your images in a ✨fancier way✨ on a\ncustom domain, such as:\n\n    docker pull r.ahmet.dev/foo\n\nThis project is a stateless reverse proxy, and can be deployed to a managed\ncompute platform such as [Cloud Run][run]. It works by reverse proxying the\n[Docker Registry API v2](https://docs.docker.com/registry/spec/api/) requests\nto the underlying registry:\n\n![architecture diagram](./docs/img/diagram.svg)\n\nIt does not support \"pushing\"; however, as you push images to the underlying\nregistry, you can serve them on your custom domain.\n\nYou are also free to fork this project and use it as a \"customizable middleware\"\nin front of your container image registry.\n\n## Building\n\nDownload the source code, and build as a container image:\n\n    docker build --tag gcr.io/[YOUR_PROJECT]/gcr-proxy .\n\nThen, push to a registry like:\n\n    docker push gcr.io/[YOUR_PROJECT]/gcr-proxy\n\n## Deploying (to Google Cloud Run) for Google Container Registry (`gcr.io`)\n\nYou can easily deploy this as a serverless container to [Google Cloud Run][run].\nThis handles many of the heavy-lifting for you.\n\n1. Build and push docker images (previous step)\n1. Deploy to [Cloud Run][run].\n1. Configure custom domain for Cloud Run service.\n   1. Create domain mapping\n   1. Verify domain ownership\n   1. Update your DNS records\n1. Have fun!\n\nTo deploy this to [Cloud Run][run], replace `[GCP_PROJECT_ID]` with the project\nID of the GCR registry you want to expose publicly:\n\n```sh\ngcloud run deploy gcr-proxy \\\n    --allow-unauthenticated \\\n    --image \"[IMAGE]\" \\\n    --set-env-vars \"REGISTRY_HOST=gcr.io\" \\\n    --set-env-vars \"REPO_PREFIX=[GCP_PROJECT_ID]\"\n```\n\n\u003e This will deploy a publicly accessible registry for your\n\u003e `gcr.io/[GCP_PROJECT_ID]`, which also [needs to be\n\u003e public](https://cloud.google.com/container-registry/docs/access-control#public).\n\u003e If your GCR registry is private, see the section below on \"Exposing private\n\u003e registries\".\n\nThen create a domain mapping by running (replace the `--domain` value):\n\n```sh\ngcloud run domain-mappings create \\\n    --service gcr-proxy \\\n    --domain [YOUR_DOMAIN]\n```\n\nThis command will require verifying ownership of your domain name, and have you\nset DNS records for your domain to point to [Cloud Run][run]. Then, it will take\nsome 15-20 minutes to actually provision TLS certificates for your domain name.\n\n\u003e Pricing Note: Cloud Run has a generous free tier. When serving from GCR using\n\u003e this proxy, the layer blobs will not be served through this proxy (as they're\n\u003e downloaded from a signed GCS URL). This saves you a lot of \"billable time\" and\n\u003e \"egress networking\" costs.\n\n## Deploying (to Google Cloud Run) for Google Artifact Registry (`*.pkg.dev`)\n\nSame instructions as GCR listed above. You need to just configure these\nenvironment variables differently:\n\n- `REGISTRY_HOST`: your regional AR domain (e.g. `us-central1-docker.pkg.dev`)\n- `REPO_PREFIX`: project ID + AR Repository name (e.g.\n  `ahmetb-demo/prod-images`)\n\n\u003e **Warning:** When using Artifact Registry, the layer blobs are downloaded\n\u003e through this proxy, and therefore will incur [more\n\u003e costs](https://cloud.google.com/run/pricing) on Cloud Run such as networking\n\u003e egress and longer execution times leading to higher \"billable time\".\n\n### Deploying (elsewhere)\n\n...is much harder. You need to deploy the application to an environment like\nKubernetes, obtain a valid TLS certificate for your domain name, and make it\npublicly accessible.\n\n### Using with other Docker Registries\n\nIf you set `REGISTRY_HOST` and `REGISTRY_PREFIX` environment variables, you can\nalso use this proxy for other docker registries.\n\nFor example, to proxy `docker pull ahmet/example` to Docker Hub, specify\nenvironment variables:\n\n- `REGISTRY_HOST=index.docker.io`\n- `REPO_PREFIX=ahmet`\n\n\u003e **Note:** This is not tested with registries other than Docker Hub and GCR/AR.\n\u003e If you can make it work with Azure Container Registry or AWS Elastic Container\n\u003e Registry, contribute examples here.\n\n### Exposing private registries publicly (GCR.io)\n\n\u003e ⚠️ This will make images in your private GCR registries publicly accessible on\n\u003e the internet.\n\n1. Create an [IAM Service\n   Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating_a_service_account).\n\n1. [Give it\n   permissions](https://cloud.google.com/container-registry/docs/access-control)\n   to access the GCR registry GCS Bucket. (Or simply, you can give it the\n   project-wide `Storage Object Viewer` role.)\n\n1. Copy your service account JSON key into the root of the repository as\n   `key.json`.\n\n1. (Not ideal, but whatever) Rebuild the docker image with your service account\n   key JSON in it. This will require editing `Dockerfile` to add `COPY` and\n   `ENV` directives like:\n\n       COPY key.json /app/key.json\n       ENV GOOGLE_APPLICATION_CREDENTIALS /app/key.json\n       ENTRYPOINT [...]\n\n   You need to rebuild and deploy the updated image.\n\n### Configuration\n\nWhile deploying, you can set additional environment variables for customization:\n\n| Key | Value |\n|-----|-------|\n| `REGISTRY_HOST` | specify  hostname for target registry, e.g. `gcr.io`. |\n| `DISABLE_BROWSER_REDIRECTS` |  if you set this variable to any value,   visiting `example.com/image` on this browser will not redirect to  `[REGISTRY_HOST]/[REPO_PREFIX]/image` to allow your users to browse the image on GCR. If you're exposing private registries, you might want to set this variable. |\n| `AUTH_HEADER` | The `Authentication: [...]` header’s value to authenticate to the target registry |\n| `GOOGLE_APPLICATION_CREDENTIALS` | (For `gcr.io`) Path to the IAM service account JSON key  file to expose the private GCR registries publicly. |\n\n-----\n\nThis is not an official Google project. See [LICENSE](./LICENSE).\n\n[run]: https://cloud.google.com/run\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahmetb%2Fserverless-registry-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fahmetb%2Fserverless-registry-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahmetb%2Fserverless-registry-proxy/lists"}