Local Editor Development Setup¶

Fast UI-iteration loop: run the Next.js editor on your laptop with Next's hot-reload (~1s per change) while the backend (AstraPBX, Pipecat gateway, Workflow engine) continues to run on the staging VPS. An SSH tunnel bridges the two.

Use this instead of editing on the VPS + ./scripts/dev-deploy.sh editor (which takes ~3-4 min per iteration because of the Next.js build).

When to use this¶

Use local dev when:

• You're iterating on UI / component styling and the 3-4 min VPS build cycle is painful
• The change is UI-only (no backend code, no Asterisk config, no DB migration)
• You want instant Fast-Refresh preview of React component edits

Stick with the VPS dev-deploy.sh editor flow when:

• You need to verify on the real stageeditor.astradial.com domain (e.g. testing Cloudflare Access interaction, production build output, CDN-cached assets)
• You're touching next.config.ts or middleware
• You've changed backend code on the VPS that the editor needs to exercise

Architecture¶

Browser (localhost:3000)
   │
   ▼
Next.js dev server (your laptop)
   │ /api/pbx/*       ──► localhost:8000 ─┐
   │ /api/gateway/*   ──► localhost:7860  ├─ SSH tunnel ─► VPS 94.136.188.221
   │ /api/workflow/*  ──► localhost:3002 ─┘                 (staging backends)
   │
   └─ Firebase Auth + Firestore ──► Google (direct, not via tunnel)

The dev server serves the UI on localhost:3000 and proxies /api/* calls through the SSH tunnel to the corresponding port on the staging VPS. Firebase auth and Firestore reads/writes go directly from the browser to Google, scoped to the astrapbx_stage/… root via NEXT_PUBLIC_ASTRADIAL_ENV=staging.

Why tunnel, not point at stage* domains directly?¶

All stage* hostnames sit behind Cloudflare Access. The editor's next.config.ts rewrites /api/pbx/* etc. server-side — the Next dev server on your laptop would then need to forward those requests to stagepbx.astradial.com, and it has no Access cookie to attach. Every call would 302 to the Cloudflare login page and break.

A tunnel sidesteps Access entirely by reaching the backends on their private port via SSH.

Prerequisites¶

One-time setup¶

1. Clone and branch¶

cd <your-projects-folder>
git clone https://github.com/astradial/astradial-platform.git
cd astradial-platform

# branch from staging — never from main or from whatever was checked out
git fetch origin
git checkout staging && git reset --hard origin/staging
git checkout -b <your-feature-branch>

2. Install editor deps¶

cd editor
npm install

Expect 2-3 min on first install. Deprecation warnings and the audit count are noisy but not blocking.

3. Seed .env.local from the staging VPS¶

The editor needs Firebase client config plus a few server secrets. Rather than curate them by hand, copy the live staging .env:

# From editor/ directory
scp root@94.136.188.221:/root/astradial-platform/editor/.env ./.env.local

Then open editor/.env.local and confirm these lines are present (add them if missing):

NEXT_PUBLIC_ASTRADIAL_ENV=staging
NEXT_PUBLIC_GATEWAY_URL=http://localhost:7860
NEXT_PUBLIC_PBX_URL=http://localhost:8000
NEXT_PUBLIC_WORKFLOW_URL=http://localhost:3002

.env.local is gitignored — it will not be committed.

4. Authorize localhost in Firebase¶

The staging Firebase project is misssellerai. Authentication → Settings → Authorized domains must contain localhost, otherwise login fails with auth/unauthorized-domain. This is a project-wide setting, so once any dev has added it, all other devs are covered.

Everyday loop (two terminals)¶

Terminal 1 — SSH tunnel (leave running)¶

ssh -L 8000:localhost:8000 -L 7860:localhost:7860 -L 3002:localhost:3002 root@94.136.188.221

Do not type in this shell — it is a pipe. Closing it breaks every API call from the editor with ECONNREFUSED.

Terminal 2 — Next.js dev server¶

cd <your-projects-folder>/astradial-platform/editor
npm run dev

Expected output:

▲ Next.js 16.x (Turbopack)
- Local:        http://localhost:3000
✓ Ready in XXXms

Open http://localhost:3000. Log in as admin@astradial.com with the password from .env.local (NEXT_PUBLIC_FB_AUTH_PASS).

Edit loop¶

1. Edit any .tsx / .ts / .css under editor/ in your editor of choice.
2. Save. Turbopack Fast-Refreshes in ~1s. Component state preserved.

Hot reload does not cover next.config.ts, middleware.ts, .env.local, or a new dependency — Ctrl+C + npm run dev again for those.

Committing¶

Push your feature branch to GitHub when done:

cd <your-projects-folder>/astradial-platform
git add editor/   # add specific paths — never `git add -A`
git commit -m "ui: <what you changed>"
git push -u origin <your-feature-branch>
gh pr create --base staging --title "..."

Never push to staging or main directly — the staging branch is CI/CD-deployed, and main is prod.

Troubleshooting¶

Environment quick-ref¶

See also: Staging Environment, Staging Direct-Edit, CI/CD Pipeline.