Skip to main 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.

RegistryURLBest For
GitHub Container Registryghcr.ioProjects hosted on GitHub
GitLab Container Registryregistry.gitlab.comProjects hosted on GitLab
Docker Hubdocker.ioGeneral use, public images
DigitalOcean Container Registryregistry.digitalocean.comDO-hosted infrastructure
AWS ECR<account>.dkr.ecr.<region>.amazonaws.comAWS-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. Go to the cluster Settings section

  3. Find the Container Registry configuration

  4. Enter the following:

    • Registry URL -- e.g., ghcr.io, registry.gitlab.com, or docker.io
    • Username -- your registry username
    • Password / Token -- your access token

  5. Save the credentials

Appliku verifies the credentials upon saving. Once verified, the credentials are:

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

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. Update the credentials in the cluster settings
  2. Appliku redistributes the new credentials to all nodes on the next deployment

Troubleshooting​

IssueSolution
Push fails with "unauthorized"Verify the token has write permissions to the registry
Pull fails on worker nodesCredentials may not have propagated -- trigger a new deployment
Image not foundCheck that the registry URL matches the image path used during build

Next Steps​