Skip to main content

Setting Up a Cluster

This guide walks you through creating a Docker Swarm cluster in Appliku.

Requirements​

  • A server for a leader node — manages the cluster and runs the Nginx load balancer
  • Optional server(s) for worker nodes — run your applications when present
  • A build server — Appliku automatically adds the cluster leader as a build server for new clusters. For production, it is recommended to use a standalone server instead, as builds can affect cluster operations.

Optional:

  • A database server outside of the cluster. Databases deployed via Appliku can only be deployed to standalone servers.

Supported OS: Ubuntu 22.04 LTS, Ubuntu 24.04 LTS, or Debian 12 with x86_64 or arm64 architecture. All servers in a cluster should have the same architecture.

Appliku will install all necessary packages and configure them, including Docker. Docker Swarm will be initialized automatically. A cluster can start with only the leader node; if there are no worker nodes, application workloads can run on the leader.

Step 1: Create a Leader Server​

Go to Servers and click "Add a Server" as usual, but instead of creating a standalone server, pick "Create a new Cluster" and give it a name, then click "Create a server".

Step 2: Wait for Leader Setup​

After creating a server as a new cluster leader, you will be taken to a new cluster page. Wait for the leader to finish setting up.

Step 3: Add Container Registry Credentials​

A container registry is required before adding a worker node or if you plan to scale beyond a single server. Without a registry, only single-node clusters where the leader is also the build server can deploy — the image stays local. Adding a worker turns the registry from optional into mandatory.

While you can use any Container Registry (CR), the easiest option is to use the CR from GitHub or GitLab, where your git repository is hosted.

When you add credentials they will be verified and added to the leader node, then distributed across all nodes upon deployment. They will also be stored to push images from the build servers after successful builds.

Step 4: Review Build Server(s)​

For a cluster to build applications, it needs one or more build servers. New clusters automatically use the leader as a build server, so this step is optional for small or test clusters. Multiple build servers are useful if you have many concurrent builds or builds that take a long time.

To use a separate build server:

  1. Add a server as usual to Appliku (standalone)
  2. Wait for setup to finish
  3. Go to your cluster, scroll down to "Build Servers", and click "Add Build Server"
  4. Select the server you prepared for this role

Add more build servers if you need them. For production, prefer a standalone build server over building on the leader.

Step 5: Create an Application in the Cluster​

  1. Create an application — as a deployment target, select your newly created cluster
  2. Add a database if needed (remember: databases can only be deployed on standalone servers, not in the cluster)
  3. Add processes and environment variables, choose build settings, and deploy

The build process is the same as for regular apps, but includes pushing the built image to the container registry and pulling it on cluster nodes.

On the Processes tab, you can set the scale for each process — the number of replicas in Docker Swarm terms.

Limitations Compared to Standalone Apps​

  • One-off jobs (release phase commands and commands run from the dashboard "Run Command") are executed from the leader node
  • Persistent Volumes are not supported for apps in clusters