Skip to content

Registry

SSM supports the following registries:

  • ACR (Azure Container Registry)
  • CUSTOM (Self-hosted Registry)
  • ECR (Amazon Elastic Container Registry)
  • GCR (Google Container Registry)
  • GHCR (GitHub Container Registry)
  • GITLAB (GitLab Container Registry)
  • HUB (Docker Hub)
  • LSCR (LinuxServer Container Registry)
  • Quay

ℹ️ Default registries

By default, the following registries will be available using anonymous access: ECR, GHCR, GCR, HUB, QUAY

Configuring a registry

1. Go to settings, "Registries" tab

registries1

2. Select a predefined integration or custom integration (see below)

ACR (Azure Container Registry)

The acr registry lets you configure ACR integration.

Variables

NameRequiredDescriptionSupported valuesDefault value when missing
clientid🔴Service Principal Client IDSee Service Principal Auth
clientsecret🔴Service Principal SecretSee Service Principal Auth

Example

image

How to create Registry credentials on Microsoft Azure Platform

Create a Service Principal

Follow the official Azure documentation.

Get the Client Id and the Client Secret of the created Service Principal

image

Go to your Container Registry and click on the Access Control (IAM) Menu

image

Click to Add a role assignment

Select the AcrPull role and assign it to your Service Principal image

CUSTOM (Self-hosted Docker Registry)

The custom registry lets you configure a self-hosted Docker Registry integration.

Variables

Env varRequiredDescriptionSupported valuesDefault value when missing
url🔴Registry URL (e.g. http://localhost:5000)
loginLogin (when htpasswd auth is enabled on the registry)password must be defined
passwordPassword (when htpasswd auth is enabled on the registry)login must be defined
authHtpasswd string (when htpasswd auth is enabled on the registry)login/password must not be defined

Examples

Configure for anonymous access

image

Configure for Basic Auth

imageimage

ECR (Amazon Elastic Container Registry)

The ecr registry lets you configure ECR integration.

Variables

Env varRequiredDescriptionSupported valuesDefault value when missing
region🔴A valid AWS Region CodeAWS Region list
accesskey🔴A valid AWS Access Key IdStandard AWS Credentials
secretaccesskey🔴A valid AWS Secret Access KeyStandard AWS Credentials

!> The AmazonEC2ContainerRegistryReadOnly Policy (or higher) must be attached to the AWS IAM User.

Examples

image

How to create an AWS IAM user and get programmatic access

1. Login to your Go to the IAM Service from your AWS Console and create a new user

image

2. Attach the AmazonEC2ContainerRegistryReadOnly policy to the user

image

3. Get your AccessKeyId and your Secret Access Key and configure SSM with them

image

FORGEJO

The forgejo registry lets you configure a self-hosted Forgejo integration.

Variables

Env varRequiredDescriptionSupported valuesDefault value when missing
url🔴Registry URL (e.g. https://forgejo.acme.com)
login🔴Gitea usernamepassword must be defined
password🔴Gitea passwordlogin must be defined
authHtpasswd string (when htpasswd auth is enabled on the registry)login/password must not be defined

Examples

Configure

imageimage

GCR (Google Container Registry)

The gcr registry lets you configure GCR integration.

Variables

Env varRequiredDescriptionSupported valuesDefault value when missing
clientemailService Account Client Email (required for private images access)See Service Account credentials
privatekeyService Account Private Key (required for private images access)See Service Account credentials

Examples

Configure for authenticated access

image

How to create a Service Account on Google Cloud Platform

1. Go to the Service Account page

2. Create a new Service Account

3. Add the Container Registry Service Role

4. Save the Service Account

5. Create a new key for the newly created Service Account

6. Download the keyfile JSON file and store it securely

7. Open the JSON file, get the client_email and private_key values and configure SSM with them

GHCR (GitHub Container Registry)

The ghcr registry lets you configure GHCR integration.

Variables

Env varRequiredDescriptionSupported valuesDefault value when missing
usernameGitHub username
tokenGitHub tokenGitHub password or GitHub Personal Token

Examples

Configure to access private images (credentials needed)

image

How to create a GitHub Personal Token

Go to your GitHub settings and open the Personal Access Token tab

Click here

Click on Generate new token

Choose an expiration time & appropriate scopes (read:packages is only needed for SSM) and generate. image

Copy the token & use it as the token value

image

GITEA

The gitea registry lets you configure a self-hosted Gitea integration.

Variables

Env varRequiredDescriptionSupported valuesDefault value when missing
url🔴Registry URL (e.g. https://gitea.acme.com)
login🔴Gitea usernamepassword must be defined
password🔴Gitea passwordlogin must be defined
authHtpasswd string (when htpasswd auth is enabled on the registry)login/password must not be defined

Examples

Configure

image

GitLab (GitLab Container Registry)

The gitlab registry lets you configure GitLab integration.

Variables

Env varRequiredDescriptionSupported valuesDefault value when missing
url🔴GitLab Registry base URLhttps://registry.gitlab.com
authurl🔴GitLab Authentication base URLhttps://gitlab.com
token🔴GitLab Personal Access Token

Examples

Configure to access images from gitlab.com

image

Configure to access images from self-hosted GitLab instance

image

How to create a GitLab Personal Access Token

Go to your GitLab settings and open the Personal Access Token page

Click here

Enter the details of the token to be created

Choose an expiration time & appropriate scopes (read_registry is only needed for SSM) and generate. image

Copy the token & use it as the token value

image

HUB (Docker Hub including private repositories)

The hub registry lets you configure Docker Hub integration.

Currently, the supported credentials are:

  • Docker Hub auth + Docker Hub Access Token
  • Docker Base64 credentials (like in .docker/config.json)
  • Docker Hub auth + Docker Hub password (not recommended)

!> By default, if you don't configure any registries, SSM will configure a default one with anonymous access.
Don't forget to configure authentication if you're using Docker Hub Private Repositories.

Variables

Env varRequiredDescriptionSupported valuesDefault value when missing
loginA valid Docker Hub Logintoken must be defined
passwordA valid Docker Hub Tokenlogin must be defined
tokenA valid Docker Hub Token (deprecated; replaced by password)login must be defined
authA valid Docker Hub Base64 Auth Stringlogin/token must not be defined

Examples

image

Configure Authentication using Login/Token

1. Login to your Docker Hub Account

image

2. Go to your Security Settings
  • Create a new Access Token
  • Copy it and use it as the token value

image

image

Configure Authentication using Base64 encoded credentials

1. Create an Access Token

See above "Configure Authentication using Login/Token"

2. Encode with Base64

Concatenate $auth:$password and encode with Base64.

For example,

  • if your auth is johndoe
  • and your password is 2c1bd872-efb6-4f3a-81aa-724518a0a592
  • the resulting encoded string would be am9obmRvZToyYzFiZDg3Mi1lZmI2LTRmM2EtODFhYS03MjQ1MThhMGE1OTI=

image

LSCR (LinuxServer Container Registry)

The lscr registry lets you configure LSCR integration.

Variables

Env varRequiredDescriptionSupported valuesDefault value when missing
username🔴GitHub username
token🔴GitHub tokenGitHub password or GitHub Personal Token

Examples

image

How to create a GitHub Personal Token

Go to your GitHub settings and open the Personal Access Token tab

Click here

Click on Generate new token

Choose an expiration time & appropriate scopes (read:packages is only needed for SSM) and generate. image

Copy the token & use it as the token value

image

Quay

The quay registry lets you configure Quay integration.

Variables

Env varRequiredDescriptionSupported valuesDefault value when missing
namespaceQuay namespace
accountQuay account
tokenQuay token

Examples

Configure to access private images (credentials needed)

image

How to create a Quay.io robot account

Go to your Quay.io settings and open the Robot Accounts tab

Click on Create Robot Account

Choose a name & create it image

Copy the part before the + sign and set it as the namespace env var

Copy the part after the + sign and set it as the account env var

Copy the token value and set it as the token env var

image

Deleting a registry

Deleting a custom registry

To delete a custom registry, simply click on "Delete" on the tile of your custom registry imageimage

Resetting a default registry

To reset a default registry, simply click on "Reset" on the tile of your custom registry image

Made with love