Self-Hosting

Mock Alpha is a standard Next.js application backed by PostgreSQL. You can run it locally for solo development, or deploy it to a server so your whole team shares one instance (recommended).

Run locally

Prerequisites

• Node.js 20+
• Docker (for PostgreSQL)

1. Clone and install

git clone https://github.com/your-org/mock-alpha.git
cd mock-alpha
npm install

2. Start the database

docker compose up -d postgres

This starts a PostgreSQL instance on localhost:5432.

3. Configure environment

Create .env.local:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/mockalpha
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=change-me-in-production

4. Run database migrations

npm run db:migrate

5. Start the dashboard

npm run dev

Open http://localhost:3000 and continue with the Quick Start — using http://localhost:3000 as your instance URL.

Reaching a local instance from a device: Android emulators use http://10.0.2.2:3000, iOS simulators use http://localhost:3000, and physical devices need your machine's LAN IP (http://192.168.x.x:3000) or adb reverse tcp:3000 tcp:3000 on Android. See the base URL table in Client Integration. A deployed instance avoids all of this.

Deploy to a server

Deploying Mock Alpha gives your team a single shared URL — no per-developer setup, no emulator IP juggling, and collaborators can manage the same projects together.

The dashboard runs as a standard Next.js application and can be deployed to any Node.js host (a VPS with Docker, Railway, Fly.io, etc.). Checklist:

1. Set NEXTAUTH_URL to your public URL (e.g., https://mock-alpha.your-domain.com)
2. Use a strong random NEXTAUTH_SECRET — openssl rand -base64 32
3. Point DATABASE_URL at a managed PostgreSQL service (Supabase, Neon, Railway) or a co-located container
4. Put the app behind HTTPS (reverse proxy such as Caddy or nginx)
5. If clients connect to MQTT directly, expose ports 1883 (TCP) and 1884 (WebSocket) — or set MQTT_ENABLED=false to disable the broker

Vercel / serverless note: the embedded MQTT broker needs a long-lived Node.js process. On serverless platforms, HTTP mocking works but MQTT does not — use a VPS or container host if you need MQTT.

For a step-by-step Ubuntu VPS deployment using the prebuilt Docker images (GitHub Actions + GHCR), see VPS_RUNBOOK.md in the repository root.

Configuration reference

All environment variables are documented in Configuration.