Private Container Registry Secrets

Koyeb allows you to easily deploy an app using Docker containers. Koyeb supports the deployment of containers hosted on any Private Docker Registry. This lets you build containers with your continuous delivery pipeline and host them on a secure private registry to protect your intellectual property.

We provide an easy-to-use form in the app and service creation views to automatically create a secret with the right format. The form supports:

Azure Container Registry (ACR)
DockerHub Private repositories
DigitalOcean Container Registry
GCP Container Registry
GitHub Container Registry (ghcr.io)
GitLab Container Registry

If you're using one the above registries, you probably don't need this documentation. Simply use the form embedded in the web interface.

Refer to how to deploy containers for generic instructions about app deployment from containers.

In this guide, we explain how to manually create secrets containing Private Registries credentials.

The Koyeb registry Secret format

To use a private registry, the Koyeb platform needs to be able to access the registry and you will need to create a secret with the login information for your registry. You will then reference the registry secret when you deploy your Service. The secret creation described below is automatically done when you use the form embedded in the web interface.

The Secret needs to contain a JSON with the right parameters for your registry:

{
  "auths": {
		"my.docker.registry.io": {
			"auth": "YOUR_TOKEN"
    }
  }
}

The my.docker.registry.io string should be replaced by your registry URL. The YOUR_TOKEN string is an authentication string which is the output of echo -n "USERNAME:TOKEN" | base64 where USERNAME and TOKEN should be replaced by your registry credentials.

Refer to the provider specific instruction section if you need help to provide the right credentials.

As a general rule, the Koyeb Secret will contain the same output as the config.json file generated by the docker login command on Linux or on Windows.

The JSON can contain either an auth field (USERNAME:TOKEN in base64) or two fields username and password (without encoding):

{
  "auths": {
		"my.docker.registry.io": {
			"username": "USERNAME",
			"password": "PASSWORD"
    }
  }
}

In both cases, the Secrets will be encrypted server-side by Koyeb.

Provider specific instructions

The Koyeb implementation is compatible with any Docker compatible registry. We provided some details on how to implement it for some major Registry Providers:

GitHub Container Registry
Dockerhub
GCP Container Registry

GitHub Container Registry

We support GitHub Container Registry and not the old GitHub Packages Docker registry. Ensure you are using an URL starting with ghcr.io.

Build and push your container

In GitHub, create a Personal access token with the write:packages permission.

Then simply log in, build, and push your container. Do not forget to replace PERSONAL_TOKEN and GITHUB_USERNAME with your own token and GitHub username.

echo PERSONAL_TOKEN | docker login ghcr.io -u GITHUB_USERNAME --password-stdin
docker build . --tag ghcr.io/koyeb-community/koyeb-debug-container:0.0.1
docker push ghcr.io/koyeb-community/koyeb-debug-container:0.0.1

Create the Koyeb Secret

In GitHub, create a Personal access token with the read:packages permission.

Then, in Koyeb, create a Secret called my-registry-secret:

{
  "auths": {
		"ghcr.io": {
			"username": "USERNAME",
			"password": "PERSONAL-ACCESS-TOKEN"
    }
  }
}

Dockerhub

Simply generate the auth string with echo -n "USERNAME:TOKEN" | base64

{
  "auths": {
		"index.docker.io/v1/": {
			"auth": "GENERATED_TOKEN"
    }
  }
}

GCP Container Registry

You will need to create a dedicated service account with a JSON key file.

To generate a valid auth token, simply execute the following command where keyfile.json is the file containing your newly created key:

echo -n "_json_key:$(cat keyfile.json)" | base64

Then, simply use the token in the secret JSON:

{
  "auths": {
        "gcr.io": {
            "auth": "GENERATED_TOKEN"
    }
  }
}