Setting Up a BYOC Server

This walks you through turning a fresh server into a place Raklane can deploy to. It usually takes about five minutes. If you haven't yet, read BYOC: Overview & How It Works first — it explains what gets installed and why.

Before you start

Server requirements

• Operating system: Ubuntu 20.04+ or Debian 11+.
• Access: root, or a user with sudo, over SSH.
• A public IPv4 address — needed for automatic HTTPS and the free default URL. (A server on a private network still works, but over plain HTTP only.)
• Resources: whatever your apps need. Builds happen on Raklane, not on your server, so you don't need extra headroom for compiling. A 1 vCPU / 1 GB server is enough to try things out.
• Disk space for your container images and any database data.

You don't need Docker pre-installed — the install command installs it if it's missing.

Network requirements

Inbound (from the public internet to your server):

Outbound (from your server to Raklane) — usually allowed by default:

• Your Raklane installation's URL over HTTPS (to download the installer and enroll).
• The Node Agent connection port on Raklane (8443 by default).
• Raklane's image registry over HTTPS (to pull your app's images).

Most common setup mistake: many cloud providers put a firewall in front of your server (AWS Security Groups, GCP firewall rules, DigitalOcean/Hetzner/Vultr cloud firewalls, etc.), separate from the firewall inside the OS. The install command opens ports 80/443 in the OS firewall (ufw), but it can't touch your cloud provider's firewall. Open 80 and 443 there too, to 0.0.0.0/0.

What you'll need to decide

• A name for the server — just a label for you in the dashboard (e.g. prod-vps-1).
• A provider label — AWS, Google Cloud, Azure, DigitalOcean, Hetzner, Bare metal / on-prem, or Other. This is only for your reference; Raklane never connects to your provider's API.
• An external host (optional) — only if your server is behind NAT or a private network and its real public IP or hostname differs from the address it connects to Raklane from. Leave it blank if you're not sure; you can set it later.

Step 1: Register the server

1. In the dashboard, open Clusters.
2. Click Add server (or Add your first server).
3. Enter the Server name, choose a Provider, and optionally an External host.
4. Click Continue.

If your installation charges a BYOC management fee, the dialog shows roughly how much a typical server adds to your monthly fee before you commit. See BYOC Billing.

The server is now registered with status Pending — Raklane is waiting for it to enroll.

Step 2: Run the install command on your server

The next screen shows an install command and the enrollment token inside it. Copy the command, SSH into the server itself (not your own computer), and run it:

curl -fsSL https://your-raklane.example.com/install/agent-install.sh \
  | sudo bash -s -- --token=YOUR_ENROLLMENT_TOKEN --control-plane=https://your-raklane.example.com

Use the exact command from the dashboard — it already has your installation's real URL and your token filled in.

The command:

1. Installs Docker, if it isn't already installed.
2. Installs Caddy, which serves your apps over HTTPS.
3. Installs the Raklane Node Agent as a systemd service called raklane-agent, so it starts on boot and restarts if it crashes.
4. Opens ports 80/443 in ufw, if ufw is active.
5. Enrolls the agent with your one-time token. The agent creates its own private key on the server, receives a certificate from Raklane, and opens its encrypted connection.

It's safe to re-run if something fails partway through.

Treat the token like a password until it's used. Anyone who has it can enroll a server as this cluster — but only once, and it stops working the moment your server enrolls.

Closed the dialog too early?

That's fine. The server stays registered as Pending. From the Clusters page, open the server's menu and choose Regenerate token to get a fresh install command. The previous token stops working immediately.

Optional install flags

You normally don't need these — the dashboard's command is complete. They exist for unusual setups:

Step 3: Confirm it's healthy

Back in the dashboard, click I've run the command, then Check now. Raklane runs three checks:

When all three pass you'll see Healthy — this server is ready for deploys. The server's card on the Clusters page also turns Healthy, usually within a few seconds of the install finishing.

If a check fails, see BYOC Troubleshooting. You can run the same checks again at any time with Check connection from the server's menu.

Step 4: Deploy something

Your server is ready. Choose it as the place your app runs:

• New app: on the last step (Review) of the create-app wizard, choose BYOC and pick your server.
• Existing app: open the app's Settings → Deployment location, choose BYOC, pick your server, and click Move deployment.

Your app is live at its default URL (like https://your-app.203.0.113.10.byoc.example.com, using your installation's BYOC domain) as soon as the deploy is active. See Running Apps & Databases on BYOC for custom domains, databases, and more.

What's on your server now

For reference, the install leaves these on your server:

To tune the agent — log verbosity, where database data is stored, automatic updates, and more — see BYOC Agent Configuration.

You still have full root access. You can inspect anything, install monitoring tools, or apply OS updates as you normally would. Avoid manually stopping or deleting Raklane-managed containers — Raklane will notice and restart them, and you'll get confusing status in the dashboard. Pause or delete the app from the dashboard instead.