UPVALE / GUIDES
Clusters and nodes
Create a cluster, connect servers, and manage networking, ingress, updates, and node maintenance.
On this page
A cluster is a group of servers running one Docker Swarm. Upvale manages deployments on those servers. Creating a cluster in Upvale does not create servers at your hosting provider.
Start with one server for a small application. Use at least three active nodes for managed HA PostgreSQL. Add workers as you need capacity and managers when you need Swarm manager redundancy.
Create your first cluster
- Open Fleet → Add cluster.
- Enter a Name, such as
production-eu, and an optional Description. - Choose the Swarm node network. Use Managed WireGuard if you want Upvale to connect servers across providers or regions. Use Private VPC / VPN if you already have a working private network. Public / mixed uses existing routed addresses and allows public addresses where needed.
- Complete the network settings described below.
- Select Create cluster.
- On the cluster page, select Add node and enroll the first manager.
The network mode cannot be changed after creation. See Networking before choosing a mode.
Your role needs Manage infrastructure to create the cluster and Manage nodes to enroll servers. Missing actions usually mean your role does not include the corresponding permission.
Cluster creation options
| Option | What it does |
|---|---|
| Name | Identifies the cluster in Fleet and workload placement selectors. |
| Description | Optional note about its purpose or location. |
| Swarm node network | Chooses the network used between servers. This is separate from public application routes. |
| Routed subnets → Name | A label for an existing VPC, VPN, or routed network. |
| Routed subnets → IPv4 CIDR | The range Upvale should use when selecting a node's Swarm address, such as 10.20.0.0/16. Required for Private VPC / VPN; optional for Public / mixed. |
| Routed subnets → Priority | Lower numbers are preferred when a node has addresses on several configured networks. |
Managed WireGuard has these settings instead of routed subnets:
| Option | Default | What it does |
|---|---|---|
| Mesh IPv4 CIDR | 10.10.0.0/16 | Private address range assigned to cluster nodes. Choose a range that does not overlap other networks you use. |
| UDP listen port | 51820 | Port used for encrypted connections between nodes. |
| WireGuard interface MTU | 1380 | Maximum packet size carried by the mesh interface. |
| Docker overlay MTU | 1330 | Maximum packet size on container overlay networks. Must be at least 50 bytes below the WireGuard MTU. |
| Advanced Docker address pool → Private IPv4 base CIDR | Automatic | Pool for Docker's container networks. Set this when automatic selection conflicts with an existing network. |
| Subnet prefix | 24 | Size of each subnet allocated from that Docker pool. For example, 24 creates /24 subnets. |
Leave the MTU and Docker pool defaults unless your network requires other values.
Enroll a server
Use a systemd-based Linux server with root access and an AMD64 or ARM64 processor. The installer can install Docker on Debian and Ubuntu. On other distributions, prepare Docker and the required host tools first. Managed WireGuard additionally requires working WireGuard and nftables support.
- Open the cluster and select Add node.
- Choose the Swarm role. The first node must be a manager.
- Leave address overrides blank unless the server needs one of the cases in the next table.
- Select Generate one-time token.
- Run 1. Install command on the server as root.
- Paste 2. Enrollment token when the installer asks for it. The terminal hides the token as you enter it.
- Return to the cluster and wait for the node to show an online state and a manager or worker role.
The enrollment token is displayed once, expires after one hour, and enrolls one server. Generate a new token for each server. The installer starts the agent, then automatic Swarm setup continues in the background.
You can also choose Fleet → Add node, select the destination cluster, and generate the enrollment command there.
| Enrollment option | When to use it |
|---|---|
| Swarm role | Managers coordinate the Swarm; workers add workload capacity. Managers can run workloads too. |
| Advertised public IPv4 | Public / mixed mode only. Use a stable public address mapped by 1:1 NAT when it does not appear on the server's interfaces. |
| WireGuard endpoint IPv4 override | Managed WireGuard only. Supplies a transport endpoint for a server behind NAT or special routing. This is not the server's private mesh address. |
| Endpoint UDP port | The externally reachable WireGuard port, useful when NAT forwards a different public port to the node's listen port. |
Use one manager for a small cluster or three for manager redundancy. An odd number avoids adding a manager without improving the number of failures the majority can tolerate. Manager redundancy is separate from database replication.
The cluster page
The page is divided into six tabs. Some tabs or actions depend on your permissions and network mode.
Cluster
Cluster details shows status, slug, Swarm ID, network mode, node count, and creation date. Nodes lists the connected servers and their role and health. Open a node's name for host details.
Repair Swarm retries forming the first manager or joining intended members to the existing Swarm. If a node says it is not in Swarm, check its displayed error and the related operation before retrying. A connected agent does not by itself mean Swarm networking is ready.
When a newer agent is available, Update agents shows the target version and eligible nodes. Confirm the update, then follow its operation. Upvale updates eligible agents separately and waits for them to reconnect. Offline or unsupported agents are reported rather than silently counted as updated. This updates the Upvale agent, not the operating system.
When HA PostgreSQL is in use, PostgreSQL HA election nodes shows the three servers that hold the shared election state. Replacing an election node does not move a database replica. To replace a permanently failed election node, keep two voters online, power off the failed server, choose Replace, and select the replacement. If the page requires election-state recovery, recover that state before replacing a voter. Database member replacement belongs on the database page.
Networking
For Private VPC / VPN and Public / mixed, this tab lists the configured routed subnets and lets you add or remove them. Each entry has a name, CIDR, and priority. A subnet used by an active node cannot be removed.
For Managed WireGuard, this tab shows the mesh address range and MTUs. Endpoint selection and tunnel health are managed automatically. The node's Overview contains peer diagnostics when you need to investigate a failed connection.
These are server networking settings. Workload overlays and public routes are covered in Networking and Routes and traffic.
Developer VPN
Available for managed WireGuard clusters. Connection chooses the VPN gateway node; People & access controls who can connect and what they may reach; Devices manages WireGuard configurations. Follow Developer VPN to give developers database access without giving them cluster management permissions.
Ingress & TLS
Choose the servers that receive public traffic, configure automatic certificates, and set any external load balancer, trusted proxy, or additional listener. Save and apply applies those settings. Redeploy ingress restarts Traefik; it does not redeploy application containers.
The full setup and every field are described in Routes and traffic.
Traefik
Browse and edit the cluster's Traefik files. Use this for custom middlewares, uploaded certificates, and advanced routing. Files directly under dynamic/ reload automatically; changes to traefik.yml require an ingress redeploy. See Editing Traefik files.
Settings
General settings edits the name and description.
Automatic cleanup schedules Docker cleanup on all nodes in the cluster:
| Option | What it removes or controls |
|---|---|
| Enable automatic cleanup | Enables the recurring cleanup operation. |
| Cron schedule | Five-field schedule; 0 3 * * * runs daily at 03:00. |
| Timezone | Timezone used for that schedule, such as UTC or Europe/Skopje. |
| Unused images older than | Removes unused tagged images after 24 hours, 7 days, or 30 days; can be disabled. Images used by containers are kept. |
| Stopped containers | Stopped containers outside Swarm. |
| Dangling images | Untagged images that are no longer used. |
| Build cache | Unused Docker build data. |
| Unused local networks | Unused local Docker networks; excludes Swarm networks. |
| Unattached anonymous volumes | Unlabeled volumes with no attached container. |
| Orphaned managed volumes | Volumes left by removed Upvale resources that are no longer in use. Unmanaged named volumes are kept. |
Select Save cleanup policy. The page shows the next run and when a cleanup was last scheduled.
Volume cleanup permanently deletes data. In particular, a volume retained when a resource was deleted may later qualify as an orphaned managed volume. Leave that category off if you intend to recover retained data.
The node page
Open a server from Fleet or a cluster's Nodes table.
| Tab | What you can do |
|---|---|
| Overview | Read host, Docker, agent, and Swarm information. Managed WireGuard nodes also show peer diagnostics. If initial address selection needs a choice, select one of the reported addresses here. |
| Monitoring | View historical CPU, memory, disk, and network measurements. |
| Containers | Search containers, filter by state, and inspect their reported image and status. |
| Volumes | Search Docker volumes and see their labels, driver, and host mount location. |
| Images | Search images and inspect tags, IDs, digests, and size. |
| Files | Browse and manage files on the host. This requires file-manager permission. |
| Terminal | Open a host terminal with terminal permission. This is a server shell, separate from a workload's container terminal. |
| Updates | Check for OS package updates and run node maintenance. |
| Cleanup | Preview and run cleanup for this one node. |
| Actions | Change the Swarm role, restart services, reboot, or remove the node. |
Update the operating system
- Open Updates and select Check now.
- Review package names, installed and available versions, and security, Docker, or kernel flags.
- Under Maintenance, keep Security updates only enabled for security updates, or clear it for all available updates.
- Select Reboot after updates when needed.
- Enter the node's name and select Run maintenance.
- Follow the operation until the node returns to service.
Maintenance drains the node, installs updates, and returns it to service. Plan for enough capacity elsewhere. A workload pinned to a local volume cannot simply resume on an arbitrary different server.
Clean up one node
Open Cleanup, choose the categories, and generate a preview. Review the listed items and estimated space before executing cleanup. The categories have the same meaning as the cluster's automatic cleanup settings. A preview lets you review one cleanup without enabling a schedule for the cluster.
Change roles or remove a node
In Actions, enter the node name to Promote to manager or Demote to worker. The last manager cannot be demoted. Keep a working manager majority.
Before Remove node, move or remove databases that depend on it and remove a Developer VPN connection hosted there. Normal removal leaves Swarm and revokes the agent's access. Follow the cleanup operation before disposing of the server.
Restart Docker interrupts containers while Docker restarts. Restart agent reconnects the management agent. Reboot server restarts the whole host. These are maintenance actions, not application deployment controls.
Recovery actions such as Remove records only and Abandon offline VPN gateway are for permanently lost servers. They remove management state without proving cleanup on the old machine. Power off or isolate that machine first; do not use them as a shortcut for normal removal.
Remove a cluster
- Remove its workloads and projects and finish active operations.
- Open Settings → Danger zone.
- Enter the cluster name and select the removal action.
- Follow the cleanup operation.
Cluster removal cleans up managed ingress and networking, removes node records, and revokes agent access. It does not uninstall Docker or clear Swarm membership on the servers. A records-only recovery option may be offered when infrastructure cleanup cannot complete; it leaves cleanup on the machines to you.
Start deploying
Open Workloads, create or select a project, and choose this cluster for its environment. Continue with Applications, Databases, or Scheduled jobs.