Skip to content

Container Registry Setup

A container registry is required for multi-node clusters and recommended for any cluster you plan to scale. When you deploy to a Docker Swarm cluster with worker nodes, Appliku builds the Docker image on a build server, pushes it to the registry, and cluster nodes pull it during deployment.

Single-node clusters where the leader is also the build server can deploy registry-less — Appliku keeps the image on the leader and skips the push/pull step entirely. As soon as a worker node is added, a registry becomes mandatory. See Single-Node Clusters for details and Cluster Limitations for the full comparison.

Why a Container Registry Is Needed

In standalone mode, the built image stays on the same server that runs the application. In a multi-node cluster, multiple servers need access to the image. A container registry acts as the shared storage layer between build servers and cluster worker nodes. On a single-node cluster (no worker nodes, no separate build server) the build server is the runtime node, so the registry hop is unnecessary.

Registry URL Best For
GitHub Container Registry ghcr.io Projects hosted on GitHub
GitLab Container Registry registry.gitlab.com Projects hosted on GitLab
Docker Hub docker.io General use, public images
DigitalOcean Container Registry registry.digitalocean.com DO-hosted infrastructure
AWS ECR <account>.dkr.ecr.<region>.amazonaws.com AWS-hosted infrastructure

Tip

The easiest option is to use the container registry from the same platform where your Git repository is hosted -- GitHub Container Registry (ghcr.io) or GitLab Container Registry. Authentication tokens are straightforward to generate.

Setting Up Credentials

Step 1: Generate an Access Token

For GitHub (ghcr.io):

  1. Go to GitHub Settings > Developer settings > Personal access tokens
  2. Create a new token (classic) with the write:packages and read:packages scopes
  3. Note your GitHub username and the generated token

For GitLab:

  1. Go to your GitLab project > Settings > Access Tokens (or use a Personal Access Token)
  2. Create a token with the read_registry and write_registry scopes
  3. The username is typically your GitLab username or the token name

For Docker Hub:

  1. Go to Docker Hub > Account Settings > Security > Access Tokens
  2. Create a new access token
  3. Use your Docker Hub username and the generated token

Step 2: Add Credentials to Your Cluster

  1. Open the Appliku dashboard and navigate to your cluster
  2. On the Registries card, click Login to Registry
  3. Enter the following (the GitHub, GitLab and DigitalOcean buttons fill in the host for you):
  4. Host -- the registry host only, e.g. ghcr.io, registry.gitlab.com, or docker.io: no https:// and no path, an optional port (for example registry.example.com:5000, at most 65535), up to 200 characters. Appliku stores the host in lower case
  5. Username -- your registry username: no spaces or control characters, up to 255 characters
  6. Password/Token -- your access token: no line breaks, up to 255 characters; other special characters are fine
  7. Save the credentials

Appliku runs docker login on the leader node with these credentials. It saves them only when the login succeeds; if the login fails, the request fails (HTTP 400) with Docker's error and nothing is saved. The password is sent to docker login on standard input, not as a docker argument, and Appliku does not show it in the logs. Once saved, the credentials are:

  • Stored on the Appliku platform
  • Used on the leader node immediately
  • Propagated to all worker nodes during deployment

The leader must be active to add a registry ("The cluster has no active primary server" otherwise).

Each cluster has its own registry credentials. You can use the same registry host on several clusters, with the same or different credentials; adding or removing it on one cluster does not change the others.

Step 3: Verify

After adding credentials, deploy an application to the cluster. The build log should show the image being pushed to your registry, and worker nodes should pull it successfully.

Credential Updates

If you rotate your access token:

  1. Click Login to Registry again and enter the same host with the new token. This replaces the credentials of that host on this cluster.
  2. Appliku redistributes the new credentials to all nodes on the next deployment

To remove a registry from the cluster, click Logout next to its host on the Registries card. This removes it only from this cluster. Appliku runs docker logout on the primary server and deletes the credentials of this host from the cluster. Then deployments cannot use this registry.

The Logout buttons are disabled while a logout runs. This can take up to about 2 minutes. Then the dashboard shows one of these messages:

Message Meaning
"The primary server is logged out from host." The logout is done.
"Logout from host refused: ..." Appliku did not start the logout, for example because you are not an owner or admin of the team, or because another registry change on this cluster is running. Nothing changed.
"Logout from host did not complete: ..." The logout command failed or could not run, for example because the primary server is not available. The registry stays on the cluster. Fix the cause, then click Logout again.
"The logout result for host is not known." The connection failed or the server gave an unexpected error. Click Logout again. A second logout is safe.

The logout runs only on the primary server. A build server that is not the primary keeps its docker login for this host. Appliku does not use it for deployments after the logout.

Troubleshooting

Issue Solution
Push fails with "unauthorized" Verify the token has write permissions to the registry
Pull fails on worker nodes Credentials may not have propagated -- trigger a new deployment
Image not found Check that the registry URL matches the image path used during build

Next Steps