BYOC Troubleshooting

Most BYOC problems come down to one of three things: a firewall (usually your cloud provider's, not the OS's), DNS that doesn't point at your server yet, or the server not being able to reach Raklane outbound. Work through the section that matches what you're seeing.

Two commands on your server answer most questions:

sudo systemctl status raklane-agent     # is the agent running?
sudo journalctl -u raklane-agent -f     # what is it doing / complaining about?

For more detail, set RAKLANE_LOG_LEVEL=debug and RAKLANE_LOG_FORMAT=text in /etc/default/raklane-agent and restart the agent. See BYOC Agent Configuration.

The agent won't start after I changed its settings

• Check the file for typos: sudo cat /etc/default/raklane-agent. Each line must be KEY=VALUE, with no spaces around =.
• Did you move RAKLANE_AGENT_STATE_DIR? Without its files, the agent tries to enroll again and fails, because the token has already been used. Move the files back, or point the setting back at the old directory.
• Did a duration setting stop having an effect? Values like 15s or 1h that can't be parsed silently fall back to the default.
• Did you re-run the install command? It rewrites the settings file and drops your custom lines. Add them back.

The server is stuck on Pending

The server registered but never enrolled.

1. Did the install command finish? Re-run it — it's safe to run again — and watch for errors.
2. Was the token already used, or replaced? Tokens work once, and regenerating one invalidates the previous one. Use Regenerate token from the server's menu and run the new command.
3. Can the server reach Raklane? From the server, run curl -I against your Raklane URL (the one in the install command). If that fails, check outbound firewall rules, DNS resolution on the server, or a corporate proxy.
4. Can the server reach the agent connection port? Enrollment can succeed but the server never turns Healthy if the agent connection port (8443 by default) is blocked outbound. The agent logs show connection errors in this case.

The server went Offline

The agent lost its connection to Raklane.

• Is the server running? Check your provider's console, then try ssh.
• Is the agent running? sudo systemctl status raklane-agent. If it's stopped, sudo systemctl restart raklane-agent.
• Did something change on the network? A new firewall rule, a changed DNS resolver, or a provider-side outage can all block the outbound connection.

The agent reconnects automatically once it can. Your apps usually keep serving visitors while the server shows Offline — "unreachable" in the dashboard means Raklane can't currently confirm their state, not that they've stopped.

The server is Healthy, but my app's URL doesn't load

This is almost always ports 80/443 being blocked in front of the server.

1. Open 80 and 443 in your cloud provider's firewall (AWS Security Group, GCP firewall rule, DigitalOcean/Hetzner/Vultr cloud firewall), to 0.0.0.0/0. The install command only opened them in the OS firewall.
2. Check the OS firewall too, if you use something other than ufw (iptables, nftables, firewalld).
3. Check nothing else is using 80/443. Another web server (nginx, Apache, a separate Caddy) on the same server prevents Raklane's Caddy from serving. sudo ss -ltnp | grep -E ':80 |:443 ' shows what's listening.
4. Confirm the deploy is actually active on the app's overview page, and that you're using the exact URL shown there.
5. Give routing a few seconds after a deploy goes active.

HTTPS doesn't work / certificate errors

• Is the domain verified? For a custom domain, the Domains page must show verified first. No certificate is requested before that.
• Does DNS point at the server? dig +short app.example.com should return your server's public IP. If it returns a CDN's IP (for example, Cloudflare with proxying on), switch to DNS-only.
• Is port 80 reachable from the internet? The certificate authority verifies over port 80, even though your app is served on 443.
• Send a real HTTPS request. Certificates are issued on the first request for a hostname; open the URL in a browser and give it a few seconds.
• Is the server's IP private? Servers with a private/LAN IP are served over plain HTTP only — this is expected, since no certificate authority can reach them.
• Hitting certificate authority rate limits? Repeatedly destroying and recreating a server, or changing many hostnames in a short time, can temporarily hit the certificate authority's limits. Wait and try again later.

My custom domain stays Pending

• The A record must point at your server's IP, not at Raklane's. The Domains page shows what the hostname currently resolves to.
• DNS changes can take time to propagate. Raklane keeps checking automatically and never gives up — if the record is right, it will verify.
• A proxying CDN in front of the domain resolves to the CDN's IP, which fails verification. Use DNS-only mode.

Deploy fails pulling the image

• server gave HTTP response to HTTPS client — your Raklane installation's registry runs over plain HTTP (development setups). Re-run the install command with --insecure-registry=HOST:PORT added (ask your Raklane operator for the value), then redeploy.
• Authentication or "not found" errors — the server may not be able to authenticate to the registry. Contact whoever operates your Raklane installation.
• no space left on device — free up disk on the server (sudo docker system prune removes unused images and stopped containers), then redeploy.
• Timeouts — check the server can reach the registry over HTTPS outbound.

A deploy that already failed doesn't retry on its own after you fix the cause — click Redeploy.

Deploy is rejected for capacity

The app's CPU/memory requests don't fit in what's left on the server. Either lower the app's requests (Resources page), move or delete other apps on that server, or use a bigger server. Remember that requests count even when the app is idle — that's what reserves the room.

Deploys to my servers are paused

Your BYOC management fee has been unpaid for longer than the grace period. Everything already running is fine. Top up your wallet from Billing — once the amount owed is collected, deploys work again. See BYOC Billing.

My app can't connect to its database

• Are they on the same server? A local database is reachable only by apps on the same BYOC server. If they're on different servers, either move the app, or make the database external and connect using its external address.
• External database not reachable? If its external address is your server's own IP, the database port must be open in both the server's and your cloud provider's firewall. If the address shown is a private IP, set the server's External host (Clusters → Edit).
• Wrong password? The password is only shown at creation. If it's lost, the database has to be recreated.

Apps show "unreachable"

Raklane can't currently confirm those apps' state, usually because the server is Offline or Docker on the server isn't responding. Check sudo systemctl status docker and the agent's status. Once the server is back, Raklane re-verifies and the apps return to active without a redeploy.

Still stuck?

Collect the output of sudo journalctl -u raklane-agent --since "1 hour ago" and the result of Check connection, and contact whoever operates your Raklane installation. See also the general Troubleshooting page.