Builds

Every deploy turns your source into a container image and rolls it out. This page covers what happens in between: the states a deployment moves through, why it sometimes waits, what a build gets to work with, and what to do when one takes too long.

The states a deployment moves through

State	What is happening
Queued	Waiting for a build slot. Nothing is being built yet.
Building	Your image is being built from the source you uploaded.
Deploying	The new image is rolling out — the new containers start and must pass their health checks before traffic moves to them.
Live	The rollout finished healthy. Your site is serving the new build.
Failed	The build errored, timed out, or the new containers never became healthy. Your previous build keeps serving — a failed deploy never takes your site down.

ghayma deploy prints each transition as it happens:


📦 Build queued (deployment: 7c1f…)
⏳ Waiting for build...

⏸️  Queued, position 3 of 7....
🔨 Building.......................
🚀 Deploying.....
✅ Deployed successfully!
🌐 Your app is live at:
   https://my-app.ghayma.app

The same states appear on your project’s Deployments tab in the dashboard .

Waiting for a slot

The platform builds a limited number of deployments at a time. When those slots are all busy, your deployment waits its turn and the CLI tells you where it stands:


⏸️  Queued, position 3 of 7

That reads as: seven deployments are waiting for a slot, and yours is third in line. The line is reprinted each time you move up.

A queued deployment means build capacity is momentarily full — nothing is wrong with your project. There is nothing to do but wait; queues normally clear in seconds to a couple of minutes. Your source is already uploaded and safe, and the site you have live keeps serving throughout.

A CLI older than the queue feature — or a deployment that has just left the queue — shows ⏸️ Queued — waiting for a build slot instead, without a position. It means the same thing.

Who goes first

Two rules decide the order:

Paid plans are prioritised over free plans. When a paid and a free deployment are both waiting, the paid one is served first. Free-plan builds are not starved — they keep getting slots, just a smaller share of them while paid deployments are queued.
At most two builds per project at once. However many deploys you fire off together, your project uses at most two build slots and the rest of your deployments queue behind them. This is what stops one busy project from filling the platform while everyone else waits — including when the busy project is somebody else’s.

What a build gets


CPU	up to 4 cores
Memory	up to 6 GB
Time limit	20 minutes

A build that has not finished within 20 minutes is stopped and the deployment is marked failed. Nothing about your running site changes — the previous build keeps serving.

ghayma deploy waits up to 25 minutes in total (the queue plus that 20-minute limit). If it gives up first, the build itself carries on inside the platform; open the deployment in the dashboard to see how it ended.

Why repeat builds are fast

Builds of the same site reuse what the last one produced:

Layers are cached between builds. A step whose inputs have not changed is not run again — so if you only changed application code, your dependency install is reused rather than repeated.
Base images are mirrored inside the platform, so the images your build pulls from don’t cross the public internet every time.
Finished images are compressed with a faster algorithm before they’re stored, which cuts the tail end of every build.

The first build of a new site has nothing to reuse, so it is the slowest — several minutes is normal, and it is not a sign of trouble. Later builds of the same site are typically much faster.

What legitimately invalidates the cache: changing your lockfile or package.json (the install layer is meant to rebuild), and editing the early lines of a custom Dockerfile — everything after the line you changed rebuilds too, which is why installs belong near the top of a Dockerfile and source copies near the bottom.

If a build times out

Read the build log

The CLI prints it automatically when a deploy fails. In the dashboard, open your project → Deployments → the failed deployment. Find the step that ran long — it is usually the dependency install or the framework’s own build.

Ship less source

A smaller upload builds faster. Add a .ghaymaignore for anything the build doesn’t need — mobile platform folders, fixtures, media, coverage output. See Ignoring files from uploads.

Build only the app you’re deploying

In a monorepo, make sure the site’s root_directory points at the one app and its upload mode ships only what that app needs. A workspace-wide build that compiles every package to deploy one of them is the most common cause of a 20-minute build. See Workspaces (monorepos).

Cut work out of the build itself

Set an explicit build_command if auto-detection is running more than you need. Type-checking and linting usually belong in CI, not in the deploy build. Dependencies you no longer import are still installed — remove them.

Retry once

A first build that ran out of time with no cache to draw on often lands well inside the limit on the second attempt, because the layers it did finish are reused.

If your build genuinely needs more than 20 minutes even with a warm cache, get in touch rather than retrying — the limit is there to keep the queue moving, and a build that big usually points at something we can help you restructure.

Migrations that run during the build

A build that runs database migrations — a prebuild script calling prisma migrate deploy, say — can fail for reasons that have nothing to do with your code, in a pattern worth recognising: the first build succeeds and every build after it fails. See Prisma and database migrations.

Deploy & Manage — the ghayma deploy command and what gets uploaded
Custom Dockerfile — bringing your own build
Points & Plans — what each plan includes