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

  1. Open Fleet → Add cluster.
  2. Enter a Name, such as production-eu, and an optional Description.
  3. Choose the Swarm node network. Managed VPN is recommended for automated WireGuard encrypted networking. Use Private VPC for an existing routed private network, or Public IP when every server has a stable public IPv4 address.
  4. Complete the network settings described below.
  5. Select Create cluster.
  6. 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

OptionWhat it does
NameIdentifies the cluster in Fleet and workload placement selectors.
DescriptionOptional note about its purpose or location.
Swarm node networkChooses the network used between servers. This is separate from public application routes.
Routed subnets → NameA label for an existing VPC, VPN, or routed network in Private VPC mode.
Routed subnets → IPv4 CIDRThe range Upvale should use when selecting a node's Swarm address, such as 10.20.0.0/16. Required for Private VPC.
Routed subnets → PriorityLower numbers are preferred when a node has addresses on several configured networks.

Public IP requires a usable public IPv4 address on every server's network interfaces and has no routed subnet settings. It does not fall back to private addresses. Use Managed VPN for servers with only private interfaces behind NAT.

Managed VPN has these settings instead of routed subnets:

OptionDefaultWhat it does
Mesh IPv4 CIDR10.10.0.0/16Private address range assigned to cluster nodes. Choose a range that does not overlap other networks you use.
UDP listen port51820Port used for encrypted connections between nodes.

Open Advanced settings for MTU values. Below them, Container network addresses configures Docker's address pool in the same toggle.

OptionDefaultWhat it does
WireGuard interface MTU1380Maximum packet size carried by the mesh interface.
Docker overlay MTU1330Maximum packet size on container overlay networks. Must be at least 50 bytes below the WireGuard MTU.
Container network addresses → Private IPv4 base CIDRAutomaticPool for Docker's container networks. Set this when automatic selection conflicts with an existing network.
Subnet prefix24Size 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 VPN additionally requires working WireGuard and nftables support.

  1. Open the cluster and select Add node.
  2. Choose the Swarm role. The first node must be a manager. Optionally select a saved Region or type a new name.
  3. For a node behind NAT, enter Server public IPv4 using the public IP shown in your hosting provider's server page. This is required when the server only sees a private address, as in some AWS and Linode setups. Otherwise leave it blank for automatic detection. Managed VPN uses this address too.
  4. Optionally select Use this node for ingress to receive public application traffic. This requires Manage infrastructure and is off by default.
  5. Select Generate one-time token.
  6. Run 1. Install command on the server as root.
  7. Paste 2. Enrollment token when the installer asks for it. The terminal hides the token as you enter it.
  8. 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 optionWhen to use it
Swarm roleManagers coordinate the Swarm; workers add workload capacity. Managers can run workloads too.
RegionOne optional region per node. New names are saved for reuse across your organization's clusters.
Use this node for ingressAutomatically enables ingress after the node joins the cluster. Requires Manage infrastructure. Change the selected nodes later in Ingress & TLS.
Swarm public IPv4Public IP mode only. Optionally overrides the address advertised to peers. The server must still have a usable local public IPv4 address for Swarm data traffic.
Server public IPv4Required when the server is behind NAT. Copy the public IP from your hosting provider. Used for app domains and Managed VPN; leave blank only when Upvale can detect the public IP on the server.

The node shows Ingress pending while waiting to be added to the ingress pool. Port conflicts appear alongside the node. Follow deployment progress in Operations or Ingress & TLS.

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.

Nodes behind NAT

Some providers give a server a public IPv4 address while its network interface only shows a private address, such as 10.0.0.2. Enter the provider's public address in Server public IPv4 during enrollment. Upvale uses it in the node's Public IP, ingress node list, and route DNS checks.

Managed VPN also tries that address on the cluster's UDP listen port, normally 51820. Allow that port through the provider firewall and forward it to the server. If WireGuard needs a different public IP or port, configure it after enrollment under Node → Overview → Managed WireGuard diagnostics → Public WireGuard endpoint.

Upvale prefers a working private path; entering a public address does not force all traffic onto the public network. See endpoint selection.

To serve public applications, select the node for ingress and allow and forward TCP 80 and 443 to it. The WireGuard UDP mapping alone does not forward web traffic.

Update an existing node's public address

Open Node → Overview → Public address, enter Public IPv4 override, and select Save public address. Clear the field and save to use the public IP detected on the server. Your role needs Manage infrastructure.

The public address is independent of Managed WireGuard diagnostics → Public WireGuard endpoint. Edit that separate setting when the tunnel needs a different public IP or UDP port, then select Save endpoint. Clearing it returns WireGuard to the public address and discovered interfaces without changing ingress DNS targets.

Wait for running cluster network operations to finish before changing either setting. Address changes keep the node's mesh IP and Swarm identity. After the mesh operation completes, if the node has not joined Swarm, select Retry Swarm join at the top of its Overview page.

Existing public addresses inferred from saved WireGuard endpoints are preserved during the upgrade. They appear as a public address override and can be edited independently.

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. Use it to retry eligible nodes together, or use Retry Swarm join on a single node's page. Check the failed 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.

To update agents across your organization, select Upgrade all in Fleet or Dashboard → Needs attention. Clusters already updating are skipped. Select View progress to follow the updates.

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, 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 VPN, 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.

Public IP uses each node's public IPv4 address and has no routed subnets to configure.

These are server networking settings. Workload overlays and public routes are covered in Networking and Routes and traffic.

Developer VPN

Available for Managed VPN 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:

OptionWhat it removes or controls
Enable automatic cleanupEnables the recurring cleanup operation.
Cron scheduleFive-field schedule; 0 3 * * * runs daily at 03:00.
TimezoneTimezone used for that schedule, such as UTC or Europe/Skopje.
Unused images older thanRemoves unused tagged images after 24 hours, 7 days, or 30 days; can be disabled. Images used by containers are kept.
Stopped containersStopped containers outside Swarm.
Dangling imagesUntagged images that are no longer used.
Build cacheUnused Docker build data.
Unused local networksUnused local Docker networks; excludes Swarm networks.
Unattached anonymous volumesUnlabeled volumes with no attached container.
Orphaned managed volumesVolumes 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.

TabWhat you can do
OverviewRead host, Docker, agent, and Swarm information. Managed VPN nodes also show peer diagnostics. If initial address selection needs a choice, select one of the reported addresses here.
MonitoringView historical CPU, memory, disk, and network measurements.
ContainersSearch containers, filter by state, and inspect their reported image and status.
VolumesSearch Docker volumes and see their labels, driver, and host mount location.
ImagesSearch images and inspect tags, IDs, digests, and size.
FilesBrowse and manage files on the host. This requires file-manager permission.
TerminalOpen a host terminal with terminal permission. This is a server shell, separate from a workload's container terminal.
UpdatesCheck for OS package updates and run node maintenance.
CleanupPreview and run cleanup for this one node.
ActionsChange the Swarm role, restart services, reboot, or remove the node.

Retry a failed Swarm join

Swarm setup allows three attempts in total: the first attempt and up to two automatic retries. Some errors, such as invalid configuration, stop the operation sooner. Once the operation fails, it stays stopped until you request another attempt; a later successful WireGuard repair does not restart the join automatically.

  1. Open the node's Overview and read the failed setup operation in Operations.
  2. Correct the reported issue. For Managed VPN, check Managed WireGuard diagnostics and wait for any network repair to finish.
  3. With the node online, select Retry Swarm join at the top of the page. Your role needs Manage infrastructure.
  4. Select View operation to follow the new operation. It has its own limit of three total attempts.

If a cluster network or node operation is still running, retry after it finishes. You do not need to remove and enroll the node again. For the first manager in a new cluster, this action retries Swarm initialization.

Update the operating system

  1. Open Updates and select Check now.
  2. Review package names, installed and available versions, and security, Docker, or kernel flags.
  3. Under Maintenance, keep Security updates only enabled for security updates, or clear it for all available updates.
  4. Select Reboot after updates when needed.
  5. Enter the node's name and select Run maintenance.
  6. 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. In Managed VPN clusters, it also removes the node's WireGuard key from the remaining peers. Follow the cleanup operation before disposing of the server.

You can remove every node. Remove workers before the final manager, and keep the final node online until removal finishes. The empty cluster remains available for adding new nodes.

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.

In Managed VPN clusters, records-only removal is available for an empty node record that never received a VPN identity or joined Swarm. Nodes with a VPN identity use Remove node, even if they have not received a Swarm address yet.

Remove a cluster

  1. Remove its workloads and projects and finish active operations.
  2. Open Settings → Danger zone.
  3. Enter the cluster name and select the removal action.
  4. 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.