Connect your own server
Add one of your own machines over SSH and let Alaf Server install everything it needs to run your apps.
Alaf Server can run your apps on a machine you already own — a cheap VPS, a spare box, a rented cloud server. You hand Alaf Server the address and a way to log in over SSH (the standard secure way to control a remote computer from a terminal), and it does the rest: it connects, checks what's already installed, and sets up the missing pieces for you.
Think of it like hiring a mover who also assembles the furniture. You give them the keys to the new place; they show up, bring the tools, and get the room ready. You don't have to install anything by hand.
What you need first
- A self-hosted Alaf Server (connecting your own servers is a self-hosted feature — on Alaf Server Cloud we run the machines for you).
- A server you can reach over SSH — Ubuntu, Debian, or a similar Linux works well.
- A way to log in: an SSH key, a password, or your machine's SSH agent.
- That's it. You do not need to pre-install Docker or anything else — Alaf Server installs what's missing.
The click-by-click way
Open the Servers page and start adding
In the dashboard, open the Servers page and press Add Server. (If this is your first server, the empty page has an Add Your First Server button that does the same thing.)
Screenshot
Fill in the SSH connection form
This is the "who am I connecting to, and how" screen. The fields:
- Server Name — an optional label like
ProductionorStaging, just so you can tell servers apart. Leave it blank and Alaf Server uses the IP address. - Server IP Address — the address of your machine, e.g.
203.0.113.10. - Port — the SSH port. Almost always
22(the default). - Username — the user to log in as. Usually
root. - Authentication — pick one:
- Password — type the server's password.
- SSH Key — give the path to your private key file (like
~/.ssh/id_ed25519) and, if the key has one, a passphrase. - Agent — use the SSH agent already running on the machine that hosts Alaf Server (like VSCode does). No password or key needed here, but that host must already be allowed to log in to the server.
There's an Advanced section too, for a Jump Host (a bastion server you must hop through first) and Extra SSH Arguments — you can ignore both unless you know you need them.
Test before you save
Press Test Connection first. Alaf Server tries to log in and reports back without saving anything. A green Connected means your details are right. Fix any red message before moving on — it saves you guessing later.
When the test passes, press Save & Continue to Setup.
Screenshot
Choose how to set the server up
Once the server is saved, Alaf Server offers two ways to install what's needed:
- Automatic Setup — one click. Alaf Server checks the server and installs everything missing for you.
- Step-by-Step Setup — you review each component and choose what to install, seeing detailed status first.
If you're new, pick Automatic Setup.
Screenshot
Watch the core components install
Alaf Server now connects over SSH and installs what your apps need to run. You'll see each piece light up as it finishes, with a live log you can expand.
Setup installs the core components first — the ones the server can't run apps without:
- Docker — the container runtime that actually runs your apps.
- Git — used to pull your source code.
The routing and certificate tools aren't installed now. Alaf Server adds them automatically later, the first time a deployment actually needs them — you never install them by hand:
- OpenResty — the reverse proxy that routes web traffic to the right app. Added the first time an app needs a public web address.
- Certbot — provisions free HTTPS certificates from Let's Encrypt, so your sites get SSL. Added the first time an app needs HTTPS.
- rsync — fast file transfer, added when a build is made elsewhere and copied to the server.
Once any of these is installed, it shows up on the server's Components tab (below), where you can re-check, reinstall, or remove it. When setup finishes, you land on the server's own page.
Screenshot
What's on the server page
Each server gets its own page, split into tabs. From here you can see how it's doing and manage it.
- Overview — live stats for the machine: CPU, memory, disk, uptime, and load, plus a quick list of which components are healthy.
- Components — the health list for this server. Re-check re-runs the checks, Install Missing installs any core components the server still needs, and each installed component can be reinstalled or removed.
- Security — request rate limiting (see below).
- Terminal — a live SSH shell right in the browser, so you can poke around the server without leaving Alaf Server. Up to 3 shells at once.
- Ports — port forwarding (desktop app only, see below).
The header also has Edit (change the connection details) and, in the "…" menu, Remove Server (which clears the stored SSH credentials and settings).
Screenshot
Rate limiting (Security tab)
Rate limiting caps how many requests a single visitor can make per second, so one noisy client (or a bad bot) can't swamp your apps. It's applied at the OpenResty level for the whole server.
Set Requests / second to turn it on. Alaf Server picks a sensible burst allowance automatically
(a small buffer for short spikes), or you can set your own under Advanced. You can also add
Whitelisted IPs — addresses or CIDR ranges (like 10.0.0.0/8) that skip the limit entirely.
Loopback (127.0.0.1, ::1) is always whitelisted. Setting requests per second back to 0 removes
the limit.
Port forwarding (Ports tab, desktop only)
If you run Alaf Server as the desktop app, the Ports tab lets you reach a port on the remote
server as localhost on your own computer — the same idea as VS Code's port forwarding. Enter the
remote port, optionally a local port (leave blank to auto-pick), and start the forward. It's
bound to loopback only and stays active just while it's running. This tab is hidden outside the
desktop app.
Prefer the terminal?
Everything above works from the CLI. You must be logged in (alaf server login) and on a self-hosted
Alaf Server.
# Add a server (this validates the connection, then saves it)
alaf server server add \
--name production \
--host 203.0.113.10 \
--user root \
--auth-method key \
--key-path ~/.ssh/id_ed25519
# List your servers to grab the id you'll need below
alaf server server list
# See what's installed on that server
alaf server server check <server-id>
# Install the missing pieces, streaming the logs live
alaf server server install <server-id> --component docker git openresty --followYou can also test a connection without saving it, watch live stats, or manage rate limiting:
# Try credentials without creating a server entry
alaf server server test-connection --host 203.0.113.10 --user root --auth-method key --key-path ~/.ssh/id_ed25519
# Stream live CPU / memory / disk stats (Ctrl-C to stop)
alaf server server monitor <server-id>
# Set a rate limit of 50 req/s (use --rps 0 to remove it)
alaf server server rate-limit <server-id> --rps 50 --burst 20The installable components are docker, git, openresty, certbot, and rsync.
If something goes wrong
Can't reach the server
Alaf Server couldn't open an SSH connection. Check that the machine is powered on, that its SSH service
is accepting connections on the port you entered (usually 22), and — if it's behind a firewall or
NAT — that the host is reachable from where Alaf Server is running. The server page shows this as a
Can't reach banner with the exact host and port.
SSH credentials rejected
Alaf Server reached the server but the login was refused. The key or password you saved doesn't match
what the server allows in its ~/.ssh/authorized_keys. Open Edit on the server and fix the
credentials, then run a health check again. If you chose Agent, make sure the host running Alaf Server
actually has a working key loaded for that server.
A component failed to install
Open the Components tab and expand the install log — the last red lines say why. Common causes are no internet access on the server or a package manager that's busy or locked. Fix it on the server, then press Re-check and Install Missing to retry just the parts that failed.
Rate limit says it can't read the config
The Security tab reads its settings from OpenResty. If OpenResty isn't installed (or isn't reachable) you'll see a "couldn't read" message. Install OpenResty from the Components tab first, then return to Security.
What next?
Backups & restore
Keep safe copies of your app's data, back it up on a schedule, and roll it back when something goes wrong — from the dashboard or the terminal.
Teams & members
Invite other people into your Alaf Server workspace, give them the right role, and understand the difference between your personal space and a shared team.