Container Registry Setup

A container registry is required for cluster deployments. When you deploy to a Docker Swarm cluster, Appliku builds the Docker image on a build server, pushes it to the registry, and cluster nodes pull it during deployment.

Why a Container Registry Is Needed

In standalone mode, the built image stays on the same server that runs the application. In cluster mode, multiple nodes need access to the image. A container registry acts as the shared storage layer between build servers and cluster worker nodes.

Recommended Registries

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. 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

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

• Deploying to a Cluster -- Deploy your first cluster application
• Setting Up a Cluster -- Full cluster creation guide