Skip to content

Cluster Limitations & Gotchas

Docker Swarm clusters provide horizontal scaling and high availability, but they come with trade-offs compared to standalone deployments. Understanding these limitations will help you plan your architecture correctly.

Key Limitations

Persistent Volumes Not Supported

Volumes are not available for applications deployed to clusters. Docker Swarm does not support shared persistent volumes across nodes natively.

Impact: Applications that rely on local file storage (e.g., user uploads saved to disk, SQLite databases) will not work correctly in a cluster.

Workaround: Use object storage (S3, DigitalOcean Spaces, etc.) for file uploads, and a managed database for persistent data.

The volumes UI is also hidden for cluster-deployed datastores: the data directory is a bind mount on the selected node, managed by Swarm. There is no migrate-to-bind-volume action for cluster datastores.

Databases: Standalone or Inside the Cluster

Databases provisioned through Appliku (PostgreSQL, Redis, RabbitMQ, etc.) can be deployed in two places:

  • On a standalone server (the original mode). The application reaches the database via its public IP.
  • Inside the same cluster as the application, on a node carrying the appliku-role-db=true Swarm label. The application reaches the database via the cluster's private overlay network (proxy), so external connectivity is not required.

When a cluster is freshly created, the leader node is automatically labeled appliku-role-db=true, so single-node clusters can host databases without extra setup. Existing clusters are not back-filled — add the label per node from the cluster page.

Recommended setups:

Single-node cluster:
Cluster Leader (also DB-labeled)  -->  Swarm manager + Nginx + databases + apps

Multi-node cluster, dedicated DB nodes:
Standalone Server (optional)  -->  Build server / external databases
Cluster Leader               -->  Swarm manager + Nginx load balancer
Cluster Worker (DB-labeled)  -->  Database containers (pinned)
Cluster Worker(s)            -->  Application containers

No migration of existing datastores. Once a datastore is created, it stays where it was placed. Adding a DB-labeled node does not move existing databases. Removing the label from a node that hosts datastores is rejected.

Tip

Single-node clusters can run application containers, builds, and databases on the leader. For production, a separate standalone build server and one or more worker nodes are recommended. Build processes consume significant CPU and RAM, which can affect cluster management operations.

One-Off Commands Run on Leader Only

Release phase commands (e.g., python manage.py migrate) and commands run from the dashboard's "Run Command" feature are launched from the leader node. If the cluster has no worker nodes, the command container can run on the leader. If worker nodes exist, Appliku places the command container on workers by default.

Impact: If the leader node has limited resources, long-running commands may affect cluster operations.

The release command and one-off commands of a cluster application run as a temporary Swarm service:

  • The command ends with the exit code of your command. If the release command fails, the deployment fails.
  • If Swarm cannot place the task on any node (for example, no worker node has enough free CPU or memory), the task stays "pending". The log shows a warning after 45 seconds and then every 3 minutes. After 10 minutes in "pending", Appliku removes the task and the command fails. The log says that the task could not be placed on any node for 10 minutes, with the reason from Swarm. For a release command, the deployment fails. Check that the cluster has worker nodes with free CPU and memory.
  • A task that Swarm rejects or stops before its end makes the command fail.

Images without GNU coreutils

Until mid-November 2026, one-off commands of a cluster application, and the release command of some cluster deployments, did not run in images whose base64 knows only -d (for example, Alpine and other BusyBox-based images), and the run showed success. Now the command runs in these images too. If Appliku cannot read the command, the run fails with "Could not decode the command (base64)".

Container Registry Required for Multi-Node Clusters

A container registry is mandatory once a cluster has any worker node, and it is recommended for any cluster you plan to scale. Single-node clusters can deploy registry-less when the leader is also the build server — the image stays local. Adding a worker or configuring registry credentials switches subsequent deployments back to the registry-backed flow.

Static Sites Build and Serve on the Load Balancer

Static sites deployed to a cluster build and serve entirely on the load balancer node. They do not use the cluster's build server, do not push to a registry, and do not run as Docker Swarm services. The load balancer builds the image, extracts the static files into the served directory, and removes the image afterwards.

Impact: Static-site builds add CPU and disk activity to the load balancer node. For very large or frequent static builds, consider this when sizing the load balancer.

Architecture Consistency

All servers in a cluster should have the same CPU architecture (either all x86_64 or all arm64). Mixing architectures causes image incompatibility issues.

Architecture Supported OS
x86_64 (amd64) Ubuntu 26.04, Ubuntu 24.04, Ubuntu 22.04, Debian 12
arm64 (aarch64) Ubuntu 26.04, Ubuntu 24.04, Ubuntu 22.04, Debian 12

Warning

Do not mix x86_64 and arm64 servers in the same cluster. Docker images built for one architecture will not run on the other.

Feature Comparison: Standalone vs. Cluster

Feature Standalone Cluster
Persistent volumes Yes No
Database hosting Yes Yes, on DB-labeled nodes (also on a standalone server)
Process scaling On/Off N replicas
Container registry Not needed Required for multi-node, optional for single-node
Multi-server No (single server) Yes (multiple nodes)
Node failure recovery Manual Automatic (Swarm rescheduling)
One-off commands Run on same server Run on leader node only
Cron jobs Yes Yes
Custom domains Yes Yes
Build location Same server Dedicated build server

When to Use Standalone vs. Cluster

Use standalone when:

  • Your application fits on a single server
  • You need persistent volumes for file storage
  • You want the simplest setup with the fewest moving parts
  • You are on the Free plan or do not need cluster scheduling

Use a cluster when:

  • You are on the Hobby plan or higher; use Growth or higher for multi-node clusters
  • You need horizontal scaling across multiple servers
  • You want automatic failover and high availability
  • Your traffic exceeds what a single server can handle
  • You want multi-cloud or multi-region deployments

Next Steps