Add a remote server
Provision isolated deployment servers and target workloads safely.
Remote deployment servers are independent Docker environments. Upstand connects over SSH, installs Docker when necessary, initializes a local Swarm, creates the attachable upstand-network, installs Caddy, and executes builds and deployments against that server's Docker daemon.
This is intentionally separate from the control-plane Swarm. Remote servers do not join the control-plane cluster and are not scheduled through manager-node placement constraints. This prevents Raft, overlay networking, and application workloads from being coupled to the Upstand control plane.
Prerequisites
- The server accepts SSH from the Upstand API server.
- You have an SSH key pair. Add the public key to the worker's
~/.ssh/authorized_keys; store the private key in SSH Keys in Upstand. - TCP 80 and 443 are available for Caddy, unless you have configured different web-server ports.
- The server has a routable address that it can advertise to its own Docker Swarm. Private/VPC addresses are supported when the server's Docker networking is configured for them.
Guided setup
- In SSH Keys, create or import a key. Copy its public key to the target server.
- In Remote Servers, choose Add Server and supply a descriptive name, IP address, SSH port, user, and the SSH key.
- Choose Setup Server. The status moves from
idletosetting_upand then toreadyorfailed. - Upstand initializes the server's own Swarm and creates
upstand-networkidempotently. - Upstand installs and starts Caddy on the server.
- When creating an application, Compose stack, or database resource, select this server. Build commands, Docker API calls, networks, services, and routing are executed on that server.
The Cluster page is the separate workflow for manually adding worker or manager nodes to the control-plane Swarm. It should be used only when shared Swarm scheduling is explicitly required.
Failure guide
| Symptom | Meaning | Fix |
|---|---|---|
| SSH authentication failed | The saved private key is not accepted | Re-copy the matching public key, verify owner and file permissions, and retry |
| Connection timed out | Control plane cannot reach SSH | Check IP, port, firewall, security groups, and VPN routing |
| Already part of a Swarm | The server has an existing independent or external Swarm | Upstand can use an active existing Swarm; leave it only when you intentionally want to replace it |
| Swarm initialization fails | The advertised address is not usable or Docker is unhealthy | Check docker info, select a routable address, and verify Docker daemon logs |
| Caddy cannot start | Ports 80/443 are occupied or the remote Docker daemon is unavailable | Free the ports or configure web-server ports, then rerun setup |
| Remote deployment cannot connect | SSH or Docker-over-SSH is unavailable | Verify the key, user permissions, Docker socket access, and SSH connectivity |
Upstand does not store an SSH password for remote provisioning. Key authentication is deliberate: it is auditable, rotatable, and avoids persisting a reusable root password. The Docker CLI uses a temporary SSH configuration for each deployment and removes it after the job completes.