Your first deployment
A gentle, screen-by-screen walkthrough of putting one real GitHub app online with Alaf Server — and what "live" actually looks like.
You're about to take some code that lives on GitHub and turn it into a real website that anyone can open. Think of it like handing a letter to the post office: you give Alaf Server your code, it does the sorting, stamping, and delivering, and out the other end comes a real web address you can click.
This page is the slow, friendly tour — we stop at every screen and explain what it means. If you'd rather do the whole thing from the terminal in a couple of commands, the Quickstart has you covered.
Before you start
- Alaf Server is up and running (you can see the dashboard). If not, start with Installation.
- You have a GitHub repository with an app in it — a website, an API, anything.
- You do not need Docker, a server config, or any special files. Alaf Server figures those out by reading your repo.
The walkthrough
Open a new project
In the dashboard, go to the Library page (the New project button lands you here too). It opens on the GitHub tab, which shows a list of your repositories.
If this is your very first time, Alaf Server won't have permission to see your repos yet — you'll see a Connect GitHub button instead of a list. Click it, say yes in the GitHub window that pops up, and the list appears. You only do this once.
Screenshot
Pick the repository you want
Find your app in the list and click it. Alaf Server reads the repo, works out what kind of app it is, and takes you to the setup screen. There's nothing to fill in by hand yet — just choose the repo.
Choose where it should run (you might not see this)
Depending on how you're running Alaf Server, it may first ask "Where do you want to deploy?" The choices are things like one of your connected servers or Alaf Server Cloud (the managed option, where Alaf Server runs the app for you).
If Alaf Server already knows where to send your app — there's only one place available, or you chose one the last time — it skips this screen and takes you straight to setup. So don't worry if you never see it. When you do, pick one and press Continue.
Tip
Not sure? The default is fine. This choice isn't permanent — you can move or redeploy the app later.
Read the setup screen
This is the one screen worth a slow look. Alaf Server has already filled it in for you by reading your code:
- The framework and commands — which kind of app it detected, plus the install and build commands it will run.
- Environment variables — an area to add any secrets or settings your app needs (like a database address). Empty is fine if your app doesn't need any.
- Project name — a short, unique name for this deployment.
On the right is a summary panel with your repository, its branch, the web address the app will get, and a Deploy button.
For most apps you change nothing here. If you see a field you don't recognize, leave it — the detected defaults are correct for the large majority of apps.
Screenshot
When it looks right, press Deploy.
Watch it go live
You land on the build screen. Two things are happening here:
- A row of steps across the top lights up one by one as each part finishes.
- A live terminal streams the build logs as they happen — like watching the oven through the glass door.
You don't have to do anything. When it's done, the title at the top changes to Deployment Successful and two buttons appear: Visit Site and View dashboard.
Screenshot
What "live" looks like
When the deployment is done, the build screen shows a Ready status in the deployment details, along with the branch it built, the framework it used, and the web address your app now lives at.
Press Visit Site and Alaf Server opens that address in a new tab — that's your app, on the internet, for real. 🎉
Where does the web address come from?
Alaf Server gives every project a web address automatically — you'll see the exact one on the setup screen and again
in the build details. Visit Site just opens it. Prefer your own name, like yourapp.com? You can attach a
custom domain afterwards.
View dashboard takes you to the project's page, your home base for this app: its deploys, logs, environment variables, and settings all live there.
If something goes wrong
No repositories show up / “Connect GitHub” keeps reappearing
Your GitHub connection didn't finish, or Alaf Server wasn't granted access to that repo. Connect again, and when GitHub asks which repositories to allow, make sure yours is included.
The build failed
Read the last few lines in the build terminal — that's the real reason, in plain text. First-time failures are almost always one of three things: a missing build command, a missing environment variable, or the app listening on the wrong port. Fix it in your repo (or in the setup screen), then redeploy.