Skip to content
Serverless reverse proxy for exposing container registries (Docker Hub, GCR etc) on custom domains
Branch: master
Clone or download
ahmetb Test commit
Signed-off-by: Ahmet Alp Balkan <>
Latest commit fcaf950 Apr 19, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs/img add svg diagram Apr 15, 2019
.gitignore support non-gcr registries Apr 19, 2019
Dockerfile Support exposing private registries Apr 3, 2019
LICENSE Add license and copyright headers Apr 10, 2019

Serverless Container Registry Proxy (for custom domains etc)

This project offers a very simple reverse proxy that lets you expose your (public or private) Google Container Registries on as a public registry on your own domain name.

For example, if you have a public registry, and offering images like:

docker pull

You can use this proxy, and instead offer your images way fancier🎩, like:

docker pull

architecture diagram


Download the source code, and build as a container image:

docker build --tag[YOUR_PROJECT]/gcr-proxy .

Then, push to a registry like:

docker push[YOUR_PROJECT]/gcr-proxy

Deploying (to Google Cloud Run) for

You can easily deploy this as a serverless container to Google Cloud Run. This handles many of the heavy-lifting for you.

  1. Build and push docker images (previous step)
  2. Deploy to Cloud Run.
  3. Configure custom domain.
    1. Create domain mapping
    2. Verify domain ownership
    3. Update your DNS records
  4. Have fun!

To deploy this to Cloud Run, replace [GCP_PROJECT_ID] with the project ID of the GCR registry you want to expose publicly:

gcloud beta run deploy \
    --allow-unauthenticated \
    --image "[IMAGE]" \
    --set-env-vars ",REPO_PREFIX=[GCP_PROJECT_ID]"

This will deploy a proxy for your[GCP_PROJECT_ID] public registry. If your GCR registry is private, see the section below on "Exposing private registries".

Then create a domain mapping by running (replace the --domain value):

gcloud beta run domain-mappings create \
    --service gcr-proxy \

This command will require verifying ownership of your domain name, and have you set DNS records for your domain to point to Cloud Run. Then, it will take some 15-20 minutes to actually provision TLS certificates for your domain name.

Deploying (elsewhere) much harder. You need to deploy the application to an environment like Kubernetes, obtain a valid TLS certificate for your domain name, and make it publicly accessible.

Using with other Docker Registries

If you set REGISTRY_HOST and REGISTRY_PREFIX environment variables, you can also use this proxy for other docker registries.

For example, to proxy docker pull ahmet/example to Docker Hub, specify environment variables:

  • REPO_PREFIX=ahmet

Note: This is not tested with registries other than Docker Hub and If you can make it work with Azure Container Registry or AWS Elastic Container Registry, contribute examples here.

Exposing private registries publicly (

⚠️ This will make images in your private GCR registries publicly accessible on the internet.

  1. Create an IAM Service Account.

  2. Give it permissions to access the GCR registry GCS Bucket. (Or simply, you can give it the project-wide Storage Object Viewer role.)

  3. Copy your service account JSON key into the root of the repository as key.json.

  4. (Not ideal, but whatever) Rebuild the docker image with your service account key JSON in it. This will require editing Dockerfile to add COPY and ENV directives like:

    COPY key.json /app/key.json
    ENTRYPOINT [...]

    You need to rebuild and deploy the updated image.


While deploying, you can set additional environment variables for customization:

Key Value
REGISTRY_HOST specify hostname for target registry, e.g.
DISABLE_BROWSER_REDIRECTS if you set this variable to any value, visiting 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.
AUTH_HEADER The Authentication: [...] header’s value to authenticate to the target registry
GOOGLE_APPLICATION_CREDENTIALS (For Path to the IAM service account JSON key file to expose the private GCR registries publicly.

This is not an official Google project. See LICENSE.

You can’t perform that action at this time.