Your first deployment
This page covers what happens after you pick a repo: framework detection, the build, the deploy phases, and what "live" means.
Prerequisite: imported a repo.
What works on Aleph Cloud
The app deploys static sites — HTML, CSS, JavaScript, and assets that a CDN can serve directly without a server runtime.
Supported frameworks (auto-detected):
| Framework | Build command | Output directory |
|---|---|---|
| Next.js (static export) | next build (with output: "export" in next.config.ts) | out/ |
| Vite | vite build | dist/ |
| Vue (Vite-based) | vite build | dist/ |
| Nuxt (static) | nuxt generate | .output/public/ or dist/ |
| Plain HTML | none | repo root or whatever directory you pick |
Auto-detection inspects your package.json and root files. You can override the build command and output directory in the wizard.
Not supported (anything that needs a server at request time):
- Next.js with API routes, middleware, or RSC streaming (full SSR)
- Nuxt without
nuxt generate(full SSR) - Remix without a static adapter
- Express, Fastify, Hono, anything with a runtime API
If your project needs server-side rendering, the sovereign tier (planned, not yet shipped) will host long-running runtimes per user. Until then, build a static export or pick a different framework.
The deploy phases
After you confirm the build config and click Deploy, the deployment row goes through these statuses. You see them in real time in the dashboard.
| Status | What's happening |
|---|---|
queued | The deploy request was accepted; GitHub Actions hasn't picked it up yet |
installing | The Actions runner is installing dependencies (npm ci or equivalent) |
building | The build command is running |
uploading | The build artifact is being uploaded to the app's backend |
pinning | The backend is pinning the artifact to IPFS via Aleph |
live | The deployment is reachable at its gateway URL |
failed | A step above broke; see the error in the deployment row |
If a step fails, the row turns red and shows the last 50 lines of build output. Open the GitHub Actions run (link in the deployment row) for the full log.
What "live" means
When a deployment reaches live, three things become true:
- The artifact is pinned on IPFS — the build output has a CID (content identifier) and is reachable through any IPFS gateway
- The CID is recorded on Aleph — a STORE message references the CID, signed by our backend's delegate key authorized by your wallet
- A gateway URL points at the CID — the deployment row shows a URL like
https://<cid>.ipfs.aleph.sh/
You can also assign a custom domain (planned for v1.1, not yet shipped). For v1, the gateway URL is the canonical address.
When something breaks
Common failures and where to look:
| Symptom | Cause | Fix |
|---|---|---|
Stuck at queued for >5 min | GitHub Actions runner queue is busy or workflow file isn't merged yet | Check the Actions tab of your repo on GitHub; merge the workflow PR if it's still open |
Fails at installing | npm ci failed — usually a package-lock.json mismatch | The workflow uses npm install rather than npm ci to tolerate this; if you still hit it, ensure package.json and package-lock.json match locally and push |
Fails at building | Build command errored | Click into the deployment row to see the captured stderr; open the linked Actions run for the full log |
Fails at uploading | Backend rate limit (50 MB per upload, 1 GB per day per wallet) | Reduce artifact size or wait until the daily quota resets at UTC midnight |
Fails at pinning | Aleph network issue | Retry the deploy; transient |
Verification
You should now see:
- A deployment row in the live state on your project's detail page
- A gateway URL (
https://<cid>.ipfs.aleph.sh/) that, when clicked, renders your site - The Verify on-chain disclosure (closed by default in the deployment row) shows the chain of Aleph messages that produced the live state
Subsequent pushes to your repo's main branch redeploy automatically. No further configuration needed.