Set Up a New Server

Set up a new server when you start from a fresh machine. One command, generated in the dashboard, installs everything Reoclo needs and connects the server to your organization. If the server already runs Docker and you only want the agent, follow the Runner setup guide instead.

What setup does

• Creates an admin user with passwordless sudo, or reuses the one your image already has (ubuntu on Ubuntu EC2 images, admin on Debian EC2 images).
• Gives that user the SSH keys from root. Keys the user already has are kept, and the “please log in as” restriction that EC2 puts on root’s key is not copied.
• Installs rootless Docker with Compose, Buildx and git, and lets containers bind ports 80 and 443.
• Configures rootless Docker so the managed proxy sees each visitor’s real IP address. This is what makes IP allowlists work.
• Installs the Reoclo runner as the admin user and registers it.
• Optionally hardens the server: no root or password SSH logins, a firewall that allows only SSH, 80 and 443, fail2ban, and automatic security updates.

Supported systems: Ubuntu 22.04 or newer and Debian 12 or newer. Setup refuses anything else before it changes the server.

Run it

1. In the dashboard, open Servers, click Add Server and choose Set up a new server.
2. Give the server a label, then pick your provider for tips and choose the options below.
3. Log in to the new server over SSH as root or as a user with sudo, paste the command and press Enter. Setup takes a few minutes.
4. The dashboard shows the server as connected as soon as the runner registers.

AWS EC2

Launch an Ubuntu 22.04+ or Debian 12+ instance and log in with your key pair as ubuntu (Debian images: admin). Set Admin user to that same user so your key pair keeps working. In the security group, allow inbound SSH (22), HTTP (80) and HTTPS (443).

Hetzner

Create an Ubuntu 22.04+ or Debian 12+ server with your SSH key and log in as root. Setup creates the admin user and gives it root’s keys. With hardening on, root can no longer log in afterwards, so log in as the admin user. If you use a Hetzner Cloud Firewall, allow 22, 80 and 443.

Other providers

Any Ubuntu 22.04+ or Debian 12+ server with a public IP works. Root or the admin user must already have your SSH key: setup refuses to run without one, so you cannot lock yourself out.

Options

Option	What it does
Admin user	The user that runs rootless Docker and the runner. Created if it does not exist. Default ubuntu.
Harden the server	Turns off root and password SSH logins, enables the firewall, fail2ban and automatic security updates. Automatic reboots stay off.
Extra open ports	Ports to allow through the firewall for apps published on other ports, for example 8080, 5432/tcp or 9000:9100/udp.
Your IP addresses	Addresses or ranges that fail2ban never bans, for example your office or VPN range. The address you run setup from is always exempt.

With the firewall on, rootless Docker publishes ports as ordinary host sockets, so the firewall filters them too. Open another port later with sudo ufw allow <port>/tcp.

Cloud-init user data

The Cloud-init user data tab gives a script you paste into the instance’s user data when you create it, on EC2, Hetzner or any provider that supports cloud-init. It runs once, as root, on first boot, and the server connects without you logging in. The registration token in it works once.

Running setup again

Setup is safe to run again on the same server. It keeps existing users, keys and Docker settings and only adds what is missing. When it changes a Docker setting on a server where Docker is already running, it tells you to restart Docker yourself, because a restart restarts every container:

systemctl --user daemon-reload && systemctl --user restart docker

Re-imaging a server

When you reinstall the operating system on a server and run setup again, it registers as a new server, even with the same hostname, because a fresh OS image gets a new machine identity. The old server stays in the list as unreachable: move its applications and domains to the new server, then decommission the old one.

Troubleshooting

Setup says the operating system is not supported

Use Ubuntu 22.04 or newer, or Debian 12 or newer.

SSH is refused right after setup

fail2ban bans an address after five failed SSH logins in ten minutes, and it counts failures from just before it started. Setup exempts the address it runs from, but logins from another address can still be banned for an hour. Wait an hour, or add your address under Your IP addresses when you set up the next server.

The Proxy tab says the proxy cannot see visitors’ IP addresses

Setup prints a warning when the br_netfilter kernel module is missing or Docker’s rootless tools are older than RootlessKit 3.0. The Proxy tab shows the exact fix for the server. See Rootless Docker for details.