Setting Up a BYOC Server
Step-by-step: prepare your server, register it, run the install command, and confirm it's ready for deploys.
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 of its own — needed for automatic HTTPS and the free default URL. (A server on a private network still works, but over plain HTTP only and only from inside that network.) VPS plans that share one public IP between many servers aren't supported — see Shared-IP VPS are not supported.
- 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):
| Port | Why |
|---|---|
80 | Automatic HTTPS: the certificate authority verifies your domain over port 80. Plain-HTTP requests are redirected to HTTPS. |
443 | Where your apps are served over HTTPS. |
22 | Your own SSH access. Raklane never uses it. |
Outbound (from your server to Raklane) — usually allowed by default:
- Raklane over HTTPS (to download the installer and enroll).
- The Node Agent connection port on Raklane (
8443by 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/443in the OS firewall (ufw), but it can't touch your cloud provider's firewall. Open80and443there too, to0.0.0.0/0.
Shared-IP VPS are not supported
Some budget VPS providers don't give each server its own public IP. Many servers share one public IP, and your server only gets a few forwarded ports — for example, SSH on port 20022 of the shared IP forwarded to port 22 on your server. Raklane can't serve apps on this kind of server: ports 80 and 443 on the shared IP belong to the provider, not to your server, so neither your visitors nor the certificate authority can reach it. The server can still enroll and even show Healthy, but your apps won't load.
Common signs: your provider's dashboard has a Port Forwarding page (often with a limited number of ports), or you SSH in on a port other than 22.
How to check your server
Run these on the server, before installing Raklane:
-
List the server's own addresses:
ip -4 addr show scope global -
Find the public IP the internet sees:
curl -4 https://api.ipify.org -
Compare them. If the IP from step 2 appears in step 1, the server has its own public IP — you're good to go.
-
If it doesn't appear (step 1 shows only a private address such as
10.x.x.x,172.16–31.x.xor192.168.x.x), the server is behind NAT. That's normal on AWS, Google Cloud, Azure and others, where the public IP is still yours alone. To find out which kind you have, check whether port80on the public IP reaches this server. Start a temporary web server on it:sudo python3 -m http.server 80Then, from your own computer (not the server), open
http://<public IP from step 2>/in a browser or runcurl http://<public IP from step 2>/.- You see a directory listing, and the server's terminal logs the request — port
80reaches your server. The public IP is yours; you're good to go. - It times out, or you see a different page — port
80doesn't reach your server. First make sure80is open in your provider's firewall (see above). If it is, and your provider only offers port forwarding, it's a shared-IP VPS.
Press
Ctrl+Con the server to stop the temporary web server. - You see a directory listing, and the server's terminal logs the request — port
If you're on a shared-IP plan, ask your provider for a dedicated public IPv4 (many sell it as an add-on), or pick a plan that includes one.
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 with its own dedicated public IP, and that 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
- In the dashboard, open Clusters.
- Click Add server (or Add your first server).
- Enter the Server name, choose a Provider, and optionally an External host.
- Click Continue.
If a BYOC management fee applies, 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://api.raklane.com/install/agent-install.sh \
| sudo bash -s -- --token=YOUR_ENROLLMENT_TOKEN --control-plane=https://api.raklane.com
Use the exact command from the dashboard — it already has Raklane's URL and your token filled in.
The command:
- Installs Docker, if it isn't already installed.
- Installs Caddy, which serves your apps over HTTPS.
- Installs the Raklane Node Agent as a systemd service called
raklane-agent, so it starts on boot and restarts if it crashes. - Opens ports
80/443inufw, ifufwis active. - 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:
| Flag | When to use it |
|---|---|
--grpc-addr=HOST:PORT | The agent connection address can't be derived from the control-plane URL (for example, you're enrolling against an IP address). Raklane support will tell you if you need this. |
--insecure-registry=HOST:PORT | The image registry is served over plain HTTP (development setups only). Can be repeated. |
Step 3: Confirm it's healthy
Back in the dashboard, click I've run the command, then Check now. Raklane runs three checks:
| Check | What it proves |
|---|---|
| Registration | The server completed enrollment with its token. |
| Heartbeat | The agent is connected right now and checking in regularly. |
| Docker Connectivity | Raklane can actually reach Docker on your server through the agent — meaning a real deploy would work right now. |
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.raklane.com, using Raklane'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:
| What | Where |
|---|---|
| Node Agent service | systemctl status raklane-agent |
| Agent logs | sudo journalctl -u raklane-agent -f |
| Agent settings | /etc/default/raklane-agent — see BYOC Agent Configuration |
| Agent identity (certificate, key) | /etc/raklane-agent/ — keep this private |
| Self-hosted database data | /var/lib/raklane-agent/ |
| Your app containers | sudo docker ps |
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.