iblai-vibe-ops-deploy

/iblai-vibe-ops-deploy

First time here? If iblai.env has no ARCHITECTURE=, run /iblai-vibe-start first (four questions; two minutes) — it decides single-org / multi-org / headless and who signs in, and every skill reads the answer.

Deploy your app's frontend through the ibl.ai platform's hosting API. The platform holds the Vercel credential for your organization — you need only the DOMAIN / PLATFORM / TOKEN already in iblai.env. No Vercel account, no Vercel token, no vercel CLI.

The hosting API is admin-only: what authorises a deploy is the platform API key your ibl.ai operator issued for the organization — the TOKEN in iblai.env, sent as Api-Token. A user's own sign-in token is not that key and every call below answers 403. If iblai.env has no TOKEN, ask the operator for one rather than substituting a personal token.

Common setup (brand, conventions, env files, verification): see docs/skill-setup.md. Headless twin: /iblai-api-hosting is the same hosting API as a plain REST reference — every deploy, poll and custom-domain call with its response fields and full error surface.

How it works: zip the app, POST it to the platform's hosting endpoint, poll until the build is READY. The address comes back as site_url on the deploy response itself — the subdomain chosen for the project under the platform's shared domain (Step 3.6, like choosing a username), or a custom domain configured for it. Public by default (no Vercel SSO/password protection to disable). POST again with the same project slug to redeploy — content identical to what is already live is skipped automatically (Step 3.5).

Read site_url, not url. url is the underlying *.vercel.app host, which Vercel mints and revises, so it stays null until a live build confirms it. site_url is the address the platform chose — and is null when the project has neither kind of domain. Never derive either from the project name.

Which target

Platform hosting (Steps 1–5 below) is the default and covers most asks. It is not the right answer when the app has to run on infrastructure the team controls:

The user said server, on-prem, self-host, our own VM, Docker, Kubernetes, air-gapped, or named an internal hostname → container, see references/docker-deploy.md.
The project already has a Dockerfile / docker-compose.yml / entrypoint.sh (skillsai and mentorai both do) → container. Deploy the way the project already deploys.
No package.json, or the app is plain HTML/JS served from a directory → static host (see the section near the end), or a container, which adds rewrites and runtime config a bare static host cannot do.

If the target is a compliance or data-residency decision — a school district, a health system, a government organization — do not pick it for them. Ask.

After the first deploy: add the URL the API reports to the organization's allowed redirect origins (ask your ibl.ai operator), or sign-in on the deployed app will never return. Localhost needs it too.

Step 1: Config

Read iblai.env (values may contain spaces — do not source it). The platform username comes from the IBLAI_USERNAME environment variable when the host provides it (the ibl.ai desktop app exports it), else from iblai.env. (Never name the variable USERNAME — zsh binds that to the OS login name and silently discards assignments.)

val() { grep -m1 "^$1=" iblai.env | cut -d= -f2-; }
DOMAIN=$(val DOMAIN); DOMAIN="${DOMAIN:-iblai.app}"
PLATFORM=$(val PLATFORM); TOKEN=$(val TOKEN)
IBLAI_USERNAME="${IBLAI_USERNAME:-$(val IBLAI_USERNAME)}"
[ -n "$IBLAI_USERNAME" ] || IBLAI_USERNAME=$(val USERNAME)   # legacy iblai.env key
AUTH="Authorization: Api-Token $TOKEN"

If IBLAI_USERNAME is still empty, ask the user once for their platform username and persist it: append IBLAI_USERNAME=… to iblai.env. Do not try to auto-detect it and do not pre-verify the token — a wrong username or token fails loudly on the first deploy call below. Then:

BASE="https://api.$DOMAIN/dm/api/ai-mentor/orgs/$PLATFORM/users/$IBLAI_USERNAME"

Step 2: Project slug + mode

PROJECT=$(jq -r .name package.json | tr '[:upper:]' '[:lower:]' \
  | sed -E 's/[^a-z0-9-]+/-/g; s/^-+//; s/-+$//' | cut -c1-64 | sed -E 's/-+$//')

grep -qs "output: *['\"]export" next.config.* && MODE=static || MODE=nextjs

project must match ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$ (max 64). Keep the slug stable — the same slug redeploys the same project and URL.

Step 3: Zip

Limits: zip ≤ 50 MB, ≤ 2000 files, ≤ 200 MB uncompressed. The platform strips .git/, node_modules/, __MACOSX/, .DS_Store, and iblai.env from the upload, but keeping them out of the zip keeps you under the limits.

Static mode (output: 'export' — Tauri shells, fully-prerendered apps): build, add the SPA rewrite file, zip the contents of out/ at the zip root:

pnpm build
printf '%s' '{"cleanUrls":true,"rewrites":[{"source":"/(.*)","destination":"/index.html"}]}' > out/vercel.json
rm -f app.zip && (cd out && zip -qr ../app.zip .)

Server mode (no output: 'export' — server actions, API routes, middleware all work): the platform installs from the lockfile and builds, so zip the app source at the zip root. Run this as ONE block, in order — .env.production is how the deployed server gets its runtime env (it rides the zip deliberately; .env* is already gitignored by the starter), and the guards abort the deploy loudly instead of shipping a broken app:

# 1. Regenerate runtime env from .env.local on every deploy (never stale)
grep -E '^(NEXT_PUBLIC_[A-Za-z0-9_]+|IBLAI_API_KEY|PAYWALL_[A-Za-z0-9_]+|CSP_MODE)=' .env.local | grep -vE '=$|=your-' > .env.production

# 2. Guard: the server needs its platform key — but only if this app reads one.
#    An app that keeps no server-side key (it calls the platform on the signed-in
#    user's own token) ships no IBLAI_API_KEY and must not be blocked here.
if grep -rq --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' --include='*.mjs' \
     --exclude-dir=node_modules --exclude-dir=.next --exclude-dir=out --exclude-dir=coverage \
     'IBLAI_API_KEY' . ; then
  grep -q '^IBLAI_API_KEY=' .env.production || { echo "ABORT: IBLAI_API_KEY missing/placeholder — fill it in .env.local"; exit 1; }
fi

# 3. Zip the source (src-tauri/target alone would blow the 50 MB cap).
#    Drop EVERY .env* and add .env.production back by name: naming the ones to
#    drop ships whatever nobody thought of — '.env*.local' does not match a
#    stray '.env.local.backup', which carries the platform key into the deploy.
rm -f app.zip
zip -qr app.zip . -x 'node_modules/*' '.git/*' '.next/*' 'out/*' 'coverage/*' \
  'playwright-report/*' 'test-results/*' 'src-tauri/target/*' 'src-tauri/gen/*' \
  '.env*' 'iblai.env' 'app.zip'
zip -q app.zip .env.production

# 4. Proof: the runtime env actually made it into the upload
unzip -l app.zip | grep -q '\.env\.production' || { echo "ABORT: .env.production not in zip"; exit 1; }

(Guard 2 decides for itself: it fires only when the app's own source reads IBLAI_API_KEY. An app that holds no server-side key passes straight through — never add one to satisfy it.)

Step 3.5: Skip if unchanged

Hash what went into the zip — never app.zip itself, which embeds mtimes and so differs on every run even when nothing changed. unzip -Z1 (already a dependency, Step 3's proof guard uses it) enumerates the members the exclude list actually produced, so the hash can never drift from what is uploaded:

ROOT=.; [ "$MODE" = static ] && ROOT=out   # zip members are relative to this
ZIP="$PWD/app.zip"
# Both print "hash<2 spaces>path", so the combined digest matches cross-OS
SHA=sha256sum; command -v sha256sum >/dev/null 2>&1 || SHA="shasum -a 256"
# per-member digest -> LC_ALL=C sorted lines -> one digest. Directory
# entries (trailing /) have no content to read.
HASH=$( (cd "$ROOT" && unzip -Z1 "$ZIP" | grep -v '/$' | tr '\n' '\0' | xargs -0 $SHA) \
  | LC_ALL=C sort | $SHA | cut -d' ' -f1 )
case "$HASH" in *[!0-9a-f]*) HASH= ;; esac   # server rejects anything but lowercase hex
[ ${#HASH} -eq 64 ] || HASH=    # any hashing hiccup -> no hash -> deploy as usual

SKIP=
if [ -n "$HASH" ]; then         # empty hash must never match a missing field
  # push_state guard: while a push is pending/uploading, the stored hash and
  # READY state still describe the *previous* deploy — skipping then would
  # report "unchanged" while different content lands (the server answers a
  # re-push with 409). Only a quiet row may satisfy the skip.
  PREV_URL=$(curl -s "$BASE/providers/vercel/hosting/deployment/" -H "$AUTH" \
    | jq -r --arg p "$PROJECT" --arg h "$HASH" '
        .projects[]? | select(.name == $p)
        | select((.push_state // "") != "pending" and (.push_state // "") != "uploading")
        | select((.deployment_hash // "") == $h)
        | select((.latest_deployment.state // .last_ready_state // "") == "READY")
        | (.site_url // "") | select(. != "")' | head -1)
  if [ -n "$PREV_URL" ]; then
    SKIP=1; APP_URL="$PREV_URL"
    echo "unchanged — already live at $APP_URL"
  fi
fi

Every edge degrades to deploying, which is today's behaviour:

First deploy — no row named $PROJECT in projects, nothing selects, deploy.
Older backend without the field — the stored hash reads empty, never equal to a 64-char digest, deploy. The extra POST field below is harmlessly dropped too: unknown form fields on the deploy request are ignored, not rejected.
Vercel unreachable — the list is served stale: true with latest_deployment: null, so the jq falls back to the row's cached last_ready_state; if neither says READY, deploy.
Older backend without site_url — the field reads empty, nothing selects, deploy. (jq's // treats null exactly like a missing key, and the select(. != "") covers the empty string, so both shapes fall through.)

ponytail: in static mode the Next.js build mints a fresh build ID every run, so identical source usually still hashes differently and the dedupe rarely fires. Server mode (the vibe-starter default) hashes app source and dedupes reliably. Upgrade path if static dedupe matters: hash the source tree before pnpm build and compare that instead.

Step 3.6: The address (first deploy only)

The platform never invents an address. A project's subdomain under the platform's shared domain is chosen, like a username, and a first deploy that names none is refused with a 400 whose body has a subdomain key.

SUBDOMAIN=$(val SUBDOMAIN)
# The address the project already has — empty on a first deploy
ADDRESS=$(curl -s "$BASE/providers/vercel/hosting/deployment/" -H "$AUTH" \
  | jq -r --arg p "$PROJECT" '.projects[]? | select(.name == $p) | (.site_url // "")' | head -1)
SUBDOMAIN_ARG=
[ -z "$ADDRESS" ] && [ -n "$SUBDOMAIN" ] && SUBDOMAIN_ARG="-F subdomain=$SUBDOMAIN"

When ADDRESS is empty and SUBDOMAIN is empty, ask the user ONE short question: the subdomain the site will live at — lowercase letters, digits and hyphens, like a username; the address becomes <subdomain>.<the platform's shared domain>. Suggest $PROJECT. Check the answer against ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$, append SUBDOMAIN=<answer> to iblai.env (printf 'SUBDOMAIN=%s\n' "$SUBDOMAIN" >> iblai.env), and set SUBDOMAIN_ARG as above. Send it only while the project has no address: a project that has one keeps it without being asked, and a recorded value re-sent on every redeploy would override a change made later through the domains route. A name that is already taken comes back as a 409 — see the error table.

Step 4: Deploy + poll

Both blocks are no-ops when Step 3.5 set SKIP — APP_URL is already the live host, so Step 5 still runs.

if [ -z "$SKIP" ]; then
  RESP=$(curl -s -X POST "$BASE/providers/vercel/hosting/deployment/" -H "$AUTH" \
    -F "file=@app.zip" -F "project=$PROJECT" -F "framework=$MODE" \
    ${HASH:+-F "deployment_hash=$HASH"} $SUBDOMAIN_ARG)
  ID=$(echo "$RESP" | jq -r .id)
  # The address of this deployment — already final here, because it is a
  # name that was chosen, not one Vercel mints and later revises. NEVER build
  # it from the project name or the subdomain: read it.
  APP_URL=$(echo "$RESP" | jq -r '.site_url // empty')
fi

A 202 returns the project row ({id, name, vercel_project_name, site_url, shared_domain, url, vercel_alias, push_state, …}), including who owns it: username, user_email and user_full_name. shared_domain is that host on its own when it is the chosen subdomain under the platform's shared domain, and empty when the site is served at a custom domain. Anything else → see the error table.

Deploying to a custom domain. Omit domain and the project keeps whatever address it already has (a first deploy needs subdomain, Step 3.6). To pin a deployment to a custom domain your organization has already configured (see references/custom-domains.md), add -F "domain=app.example.com". A domain nobody has configured is a 400.

A domain another organization holds is also a 400 — unless that organization's site no longer serves it, in which case the deployment takes the domain over and the other organization is detached. That is checked before anything is created, so a refused domain leaves nothing behind.

Poll until the build finishes (static deploys take seconds, server builds a few minutes; give up after ~10 min):

STATE=BUILDING; TRIES=0
[ -n "$SKIP" ] && STATE=READY   # nothing was pushed — the loop below never runs
until [ "$STATE" = "READY" ] || [ "$STATE" = "ERROR" ] || [ "$STATE" = "PUSH_FAILED" ] || [ $TRIES -ge 60 ]; do
  sleep 10; TRIES=$((TRIES+1))
  R=$(curl -s "$BASE/providers/vercel/hosting/deployment/$ID/" -H "$AUTH")
  case "$(echo "$R" | jq -r .push_state)" in
    failed) echo "push failed: $(echo "$R" | jq -r .push_error)"; STATE=PUSH_FAILED ;;
    # .deployment is the PREVIOUS deployment until the new push lands — read
    # it only after push_state reaches "pushed", or a stale READY masks failure
    pushed)
      STATE=$(echo "$R" | jq -r '.deployment.ready_state // "BUILDING"')
      # site_url was already known at Step 4; re-read it only in case a name
      # collision moved it (rare, and the server records the move).
      SITE=$(echo "$R" | jq -r '.site_url // empty')
      [ -n "$SITE" ] && APP_URL="$SITE" ;;
  esac
done
echo "$STATE ${APP_URL:-'(no address reported)'}"

APP_URL is set before the loop starts, so it is known while the build runs — the site simply does not serve until READY. If it is empty, read .site_domain_error: it says why. Empty too? Then none was attempted — use url once READY, or choose one (custom domains).

On PUSH_FAILED, the printed push_error says why the upload never reached Vercel (fix it, rebuild the zip, POST again). On ERROR, print the build log tail and fix what it reports:

curl -s "$BASE/providers/vercel/hosting/deployment/$ID/" -H "$AUTH" | jq -r '.build_log_tail'

Redeploy = rebuild the zip, POST again with the same project — and when the rebuilt content hashes to what is already live, Step 3.5 turns that into a no-op instead of a push.

Step 5: Update Tauri (if present)

If src-tauri/tauri.conf.json exists and APP_URL is known, set build.devUrl to it so mobile/desktop dev builds load the hosted frontend. (Skip if it is empty — never write a guessed one.)

Errors

Status	Meaning	Fix
—	No upload happened: Step 3.5 matched the live `deployment_hash` and READY state	Expected — the URL printed is the current one. To force a push anyway, set `HASH=` (and `SKIP=`) before Step 4
400	No Vercel credential stored for this organization, bad zip, or a malformed `deployment_hash` (server requires exactly 64 lowercase hex chars)	A platform admin adds a "Vercel" integration credential in the platform credentials UI (or the instance provides one); for zip errors check the size/file-count limits; for a hash error unset `HASH` and redeploy
400	The `domain` you named is not configured for this organization, or another organization holds it and still serves it	Configure it first (see references/custom-domains.md). A domain held by an organization whose site no longer serves it is taken over automatically, so this means the other one is still live on it
400	The `domain` you named is attached to another of your organization's projects	Detach it there first — a domain serves one project at a time
400	The `domain` you named is reserved: the shared subdomain namespace (chosen with `subdomain`, not `domain`), or a provider-owned host such as `*.vercel.app`	Deploy to a domain your organization owns and has configured, or send `subdomain`
400	The body has a `subdomain` key: the project has no address yet and none was chosen, the label is malformed, or `domain` and `subdomain` were both sent	The platform never invents an address — ask the user for a subdomain (Step 3.6), record it in `iblai.env`, redeploy
402	Deploy credit cost unmet	Top up platform credits
403	`TOKEN` is not the organization's platform API key, or it belongs to another `PLATFORM` — hosting is admin-only	Use the `TOKEN` your operator issued for this `PLATFORM`; a personal sign-in token cannot deploy
409	A push for this project is already in flight; the `project` slug collides; or the `subdomain` is taken — `error` names the host and says so	Wait for the running push to finish; pick another `project` slug; or drop the `SUBDOMAIN=` line from `iblai.env`, ask the user for a different subdomain and redeploy
429	Rate limited	Wait the `Retry-After` seconds, then retry
502	Vercel rejected the organization's stored credential	Admin re-saves a valid credential in the credentials UI
503	The deployment would have no address: this project has no custom domain of its own, and the platform's shared domain is offered but unreachable — or a `subdomain` was sent while no shared domain is on offer for this organization. When no shared domain is offered at all and none was sent, the deploy is accepted (202) with `site_url: null` instead	Nothing was uploaded. Either configure a custom domain for the project (see the custom-domains reference) and redeploy with `-F "domain=…"`, or ask your ibl.ai operator to fix the shared domain — the error names the setting

Custom Domain (optional)

Attaching a domain, handing the user the DNS records to set, re-verifying one, reclaiming one and detaching it — every route and response field is in references/custom-domains.md.

Deploy to a server the team controls

Full recipe — Dockerfile (Next.js and static shapes), nginx routes, entrypoint, compose, TLS, CI smoke test — in references/docker-deploy.md. The shape:

docker build -t <app> .
docker run -d -p 8080:8080 \
  -e NEXT_PUBLIC_IBL_PLATFORM=<tenant> \
  -e NEXT_PUBLIC_API_BASE_URL="${NEXT_PUBLIC_API_BASE_URL:-https://api.iblai.app}" \
  <app>

Two rules decide whether the deploy survives contact with a second environment:

One image, every environment. No organization, no backend, no customer baked in. The digest that passed staging is the digest that runs production, and repointing is a restart. See Runtime configuration below — do that part before containerizing, not after.
Reproduce the SSO callback route. The ibl.ai Auth SPA returns to <origin>/sso-login-complete. A static server that does not map that path 404s the callback and login dies with no useful error. Next.js routing handles it; nginx, S3 and GitHub Pages do not, unless told.

Static host

For an app with no build step, or an existing bucket/host:

Render the config file the browser reads (below) for the target environment, not the developer's.
Upload the served directory.
Reproduce the /sso-login-complete → /sso-login-complete.html rewrite in the host's config.
Serve that config file Cache-Control: no-store. Cached, a repointed deployment keeps sending returning users to the old backend — and it looks like the repoint silently failed.

Runtime configuration

Read references/runtime-config.md before any deploy that is not throwaway.

An ibl.ai frontend is defined by which backend it talks to. Baked in at build time — inlined NEXT_PUBLIC_*, a hand-edited committed config — those values make an artifact that can only ever be one environment: staging and production become different builds, and repointing means a rebuild. Rendering them at process start from the environment is what every ibl.ai app that ships to a server already does (window.__ENV__ in skillsai/mentorai).

Every target: the organization has to know the origin

Add the deployment's origin to the organization's allowed redirect origins. Sign-in leaves for the login SPA and returns to <origin>/sso-login-complete; an origin the organization does not know is a login that never comes back — and the symptom looks like a broken app, not a missing setting.

When to Deploy

Before running dev builds (pnpm exec tauri dev, … tauri ios dev, … tauri android dev) so the WebView loads from a network URL
After frontend changes when iterating on dev builds
When sharing a preview URL
When handing an app to someone who has to run it on their own infrastructure — that is the container path, and it is worth setting up before they ask

Going Back to Local

Remove devUrl from src-tauri/tauri.conf.json; the WebView loads local static files again.

Reference

Container/server: references/docker-deploy.md
Runtime config: references/runtime-config.md
Custom domains: references/custom-domains.md