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=trueSwarm 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.
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.
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 22.04, Ubuntu 24.04, Debian 12 |
| arm64 (aarch64) | Ubuntu 22.04, Ubuntu 24.04, Debian 12 |
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
- Clusters Overview -- How Docker Swarm works in Appliku
- Setting Up a Cluster -- Step-by-step cluster creation
- Scaling in Clusters -- Configure process replicas