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.

In this guide, we explain how to manually create Secrets containing private registry 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": {
    "<YOUR_REGISTRY_URL>": {
      "auth": "<YOUR_TOKEN>"
    }
  }
}

The <YOUR_REGISTRY_URL> string should be replaced by your registry URL.

The <YOUR_TOKEN> string is a Base64-encoded authentication string. You can generate a compatible string by typing:

echo -n "<USERNAME>:<TOKEN>" | base64

Replace the <USERNAME> and <TOKEN> placeholders with your registry credentials.

Refer to the provider specific instruction section if you need help providing 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 (set to USERNAME:TOKEN encoded in Base64) or two fields without encoding: username and password:

{
  "auths": {
    "<YOUR_REGISTRY_URL>": {
      "username": "<USERNAME>",
      "password": "<PASSWORD>"
    }
  }
}

Remember to modify the <YOUR_REGISTRY_URL>, <USERNAME>, and <PASSWORD> to match the values associated with your registry.

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

Provider specific instructions

Koyeb's implementation is compatible with all Docker-compatible registries. Below, we provide details on how to add private registry secrets for some of the most common registry providers:

• GitHub Container Registry
• DockerHub
• GCP Container Registry

Contact us if you need help or if your registry provider is not yet documented!

GitHub Container Registry

Build and push your container

In GitHub, create a Personal access token (opens in a new tab) with the write:packages permission.

Afterwards, log in, build, and push your container:

echo "<PERSONAL_ACCESS_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 (opens in a new tab) 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

Generate an auth string with the following command, replacing <USERNAME> and <TOKEN> with the values associated with your registry:

echo -n "<USERNAME>:<TOKEN>" | base64

Replace the <GENERATED_TOKEN> placeholder in the JSON below with the output from the previous command to configure authentication to your private registry:

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

GCP Container Registry

First, create a dedicated service account with a JSON key file (opens in a new tab).

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

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

Next, replace the <GENERATED_TOKEN> placeholder in the JSON below with the output from the previous command:

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