Skip to 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 can also run inside the cluster on nodes with the DB role, see Cluster Limitations.

Supported OS: Ubuntu 26.04 LTS, Ubuntu 24.04 LTS, Ubuntu 22.04 LTS, or Debian 12 with x86_64 or arm64 architecture. Appliku does not set up new servers on Ubuntu 20.04 or older. 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".

The form suggests a free name, for example my-team-cluster-1. A cluster name must be unique in the team; if the name is used, the form shows "A cluster with this name already exists."

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: Add Worker Nodes (Optional)

You can add workers in two ways. Both need a container registry on the cluster first; without it, Appliku refuses with "Add a container registry to the cluster first. Nodes get the app images from it."

  • A new server. Add a server as usual and select the cluster in the cluster picker of the add-server form. The picker shows only clusters that can take a server now ("Only clusters ready to accept a server are shown."): the leader is active and set up, and the cluster has a registry. A cluster that has no leader any more (its first server is deleted) is also shown; the new server then becomes the leader.

If the first server of a cluster failed its setup, the cluster cannot take other servers. The error message tells you what to do: remove a failed custom server on its server page; for a failed cloud server, delete its machine at the cloud provider and open its server page in Appliku, so that it shows as deleted. Then add servers again. - An existing server. See Add an Existing Server below.

All servers in a cluster should have the same CPU architecture. Appliku does not check this when a server joins.

Step 5: 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 6: 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, on a standalone server or on a cluster node with the DB role (see Cluster Limitations)
  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.

Cluster Join Status

Each server that joins a cluster has a join status. The server page shows it in the Cluster row, the cluster page shows it in the Join column of the Nodes table:

Status Meaning
Joining… Appliku runs docker swarm join on the server.
Joined The server is a node of the cluster's Swarm.
Join failed The join did not work, or the node is not in the Swarm any more. The error is shown next to the status. The server list shows "Cluster join failed".
Removing… The server is being removed from the cluster. "Removing… (nginx setup)" means it has left the Swarm and Appliku sets up its own nginx again.

The leader does not join; it creates the Swarm, so it has no join status.

When the first join fails, Appliku tries again after 1 minute, 5 minutes and 15 minutes. Some errors are not retried, for example when the server is in another Swarm or the cluster is not ready. After the last attempt, the team gets a notification. A join that is still running after 30 minutes changes to Join failed.

To try again, click Retry join on the server page or on the cluster page. The button shows only for a failed join. The status updates in about a minute.

If the error says that the server is in another Swarm, run docker swarm leave --force on the server, then click Retry join.

The cluster page also has a table Other servers of this cluster. It lists servers of the cluster that are not in the Nodes table, for example a server that is stopped, did not join, or is being removed.

Add an Existing Server

Owners and admins of the team can add a standalone server to the cluster as a worker:

  1. Open the cluster page.
  2. On the Nodes card, click Add existing server.
  3. Select the server and click Join cluster.

The server must:

  • be a standalone server of the same team, running, with its setup finished;
  • use the dockerized nginx (older servers with nginx installed on the host cannot join);
  • have no apps and no databases. Move or delete them first.

A server with the managed firewall cannot join a cluster that still uses the legacy firewall. Switch the cluster to the managed firewall first, or switch the server back to legacy. A Hetzner Cloud server cannot be a node of a cluster with the legacy firewall at all: switch the cluster to the managed firewall first.

When the server joins, its own nginx stops. The cluster load balancer serves the traffic. The join is written to the server setup log and the status shows on the cluster page.

Remove a Worker From the Cluster

Owners and admins can remove a worker node: in the Nodes table, open the node menu and click Remove from cluster.

Appliku then:

  1. Drains the node, so that Docker Swarm moves its tasks to other nodes. Appliku waits up to 5 minutes for them to start there.
  2. Runs docker swarm leave on the node and removes the node from the Swarm.
  3. Sets up the server's own nginx again. The server is then a standalone server.

The progress is in the server setup log, and the team gets a notification at the end. Data in app volumes on the removed server does not move. If the services do not start on other nodes within 5 minutes, the removal stops, the node becomes available again, and the message names the services (check their placement constraints and volumes). If the server does not answer, Appliku removes the node from the Swarm anyway; then run docker swarm leave --force and the server setup on the server. If the nginx of the server does not start, use Repair nginx on the server page (see Nginx Management).

Appliku refuses to remove:

  • the leader, a manager or the load balancer node (only workers can be removed here);
  • a node that hosts datastores ("Move the datastores first");
  • the last running worker, when the cluster has apps that run only on workers (apps without Allow placement on manager nodes, see Placement Constraints): add another worker first;
  • a node whose join still runs;
  • on a cluster without a registry, the only build server of the cluster, or a build server that builds now.

Clusters List

The Clusters page shows only active clusters: clusters whose leader is active. Turn on Show all clusters to also see clusters that are setting up, stopped, failed or deleted.

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