Skip to content

Commit 7cb2cb1

Browse files
promptless[bot]promptless[bot]
committed
Document QEMU local emulator and CLI commands
Expands the self-host documentation to cover the new QEMU-based local emulator introduced in PR #1266. Adds documentation for: - QEMU emulator prerequisites and installation - CLI commands (pull, start, stop, reset, status, list-releases) - Bundled services and port mappings - Hardware acceleration notes - Integration with local emulator mode for config file-based projects Also adds code examples for emulator CLI commands.
1 parent a93a868 commit 7cb2cb1

2 files changed

Lines changed: 145 additions & 3 deletions

File tree

‎docs/code-examples/self-host.ts‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,5 +102,55 @@ pnpm start:dashboard`,
102102
filename: 'Terminal'
103103
}
104104
] as CodeExample[],
105+
106+
'emulator-install': [
107+
{
108+
language: 'Shell',
109+
framework: 'npm',
110+
code: `npx @stackframe/stack-cli emulator pull`,
111+
highlightLanguage: 'bash',
112+
filename: 'Terminal'
113+
}
114+
] as CodeExample[],
115+
116+
'emulator-start': [
117+
{
118+
language: 'Shell',
119+
framework: 'npm',
120+
code: `npx @stackframe/stack-cli emulator start`,
121+
highlightLanguage: 'bash',
122+
filename: 'Terminal'
123+
}
124+
] as CodeExample[],
125+
126+
'emulator-stop': [
127+
{
128+
language: 'Shell',
129+
framework: 'npm',
130+
code: `npx @stackframe/stack-cli emulator stop`,
131+
highlightLanguage: 'bash',
132+
filename: 'Terminal'
133+
}
134+
] as CodeExample[],
135+
136+
'emulator-reset': [
137+
{
138+
language: 'Shell',
139+
framework: 'npm',
140+
code: `npx @stackframe/stack-cli emulator reset`,
141+
highlightLanguage: 'bash',
142+
filename: 'Terminal'
143+
}
144+
] as CodeExample[],
145+
146+
'emulator-status': [
147+
{
148+
language: 'Shell',
149+
framework: 'npm',
150+
code: `npx @stackframe/stack-cli emulator status`,
151+
highlightLanguage: 'bash',
152+
filename: 'Terminal'
153+
}
154+
] as CodeExample[],
105155
}
106156
};

‎docs/content/docs/(guides)/others/self-host.mdx‎

Lines changed: 95 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Self-host
3-
lastModified: "2026-03-10"
3+
lastModified: "2026-04-06"
44
---
55

66
<Info type="danger">
@@ -78,13 +78,105 @@ You can also open Prisma Studio to see the database interface and edit data dire
7878

7979
<PlatformCodeblock document="others/self-host" examples={["prisma-studio"]} hidePlatformSelector />
8080

81+
## QEMU Local Emulator
82+
83+
The QEMU local emulator packages the entire Stack Auth backend into a single virtual machine image. It bundles PostgreSQL, Redis, ClickHouse, MinIO, Inbucket, Svix, QStash, and the Stack Auth dashboard and backend—everything you need for local development without setting up individual services.
84+
85+
### Prerequisites
86+
87+
Before using the emulator, make sure you have:
88+
89+
- **QEMU** installed on your system (for running the virtual machine)
90+
- **GitHub CLI** (`gh`) installed and authenticated (for downloading emulator images)
91+
92+
On macOS, install with Homebrew:
93+
94+
```bash
95+
brew install qemu gh
96+
```
97+
98+
On Linux (Debian/Ubuntu):
99+
100+
```bash
101+
sudo apt install qemu-system gh
102+
```
103+
104+
### Getting Started
105+
106+
Pull the latest emulator image and start it:
107+
108+
<PlatformCodeblock document="others/self-host" examples={["emulator-install"]} hidePlatformSelector />
109+
110+
<PlatformCodeblock document="others/self-host" examples={["emulator-start"]} hidePlatformSelector />
111+
112+
The emulator automatically downloads the latest image if none exists locally. On first start, it may take a minute to boot. Subsequent starts are faster due to snapshot caching.
113+
114+
### Emulator Commands
115+
116+
The Stack CLI provides commands to manage the emulator:
117+
118+
| Command | Description |
119+
|---------|-------------|
120+
| `emulator pull` | Download the latest emulator image |
121+
| `emulator start` | Start the emulator (auto-pulls if needed) |
122+
| `emulator stop` | Stop the emulator (preserves data) |
123+
| `emulator reset` | Wipe all data and reset to a fresh state |
124+
| `emulator status` | Show emulator and service health |
125+
| `emulator list-releases` | List available emulator releases |
126+
127+
### Bundled Services
128+
129+
The emulator runs these services inside the virtual machine:
130+
131+
| Service | Host Port | Description |
132+
|---------|-----------|-------------|
133+
| Dashboard | 26700 | Stack Auth dashboard UI |
134+
| Backend | 26701 | Stack Auth API server |
135+
| MinIO | 26702 | S3-compatible storage |
136+
| Inbucket | 26703 | Email testing interface |
137+
138+
PostgreSQL, Redis, ClickHouse, Svix, and QStash run internally and are not exposed to the host.
139+
140+
### Using the Emulator with Your App
141+
142+
Once the emulator is running, configure your app to connect to the local backend:
143+
144+
```
145+
NEXT_PUBLIC_STACK_API_URL=http://localhost:26701
146+
```
147+
148+
Open the dashboard at [http://localhost:26700](http://localhost:26700) to create projects and manage users. Check Inbucket at [http://localhost:26703](http://localhost:26703) to view test emails.
149+
150+
### Hardware Acceleration
151+
152+
The emulator uses hardware acceleration when available:
153+
- **macOS**: Uses HVF (Hypervisor.framework) for native architecture
154+
- **Linux**: Uses KVM when available
155+
- **Cross-architecture**: Falls back to software emulation (slower)
156+
157+
For best performance, run the emulator on your native architecture (arm64 on Apple Silicon, amd64 on Intel/AMD).
158+
159+
### Managing Emulator Data
160+
161+
To stop the emulator while preserving your data:
162+
163+
<PlatformCodeblock document="others/self-host" examples={["emulator-stop"]} hidePlatformSelector />
164+
165+
To check the status of the emulator and its services:
166+
167+
<PlatformCodeblock document="others/self-host" examples={["emulator-status"]} hidePlatformSelector />
168+
169+
To wipe all data and start fresh:
170+
171+
<PlatformCodeblock document="others/self-host" examples={["emulator-reset"]} hidePlatformSelector />
172+
81173
## Local Emulator Mode
82174

83-
**Local emulator mode** lets you map projects to local config files during development, instead of creating them through the dashboard.
175+
**Local emulator mode** lets you map projects to local config files during development, instead of creating them through the dashboard. This is automatically enabled when using the QEMU emulator.
84176

85177
### Enabling Local Emulator Mode
86178

87-
Set this environment variable in both your backend and dashboard `.env` files:
179+
If you're running the QEMU emulator, local emulator mode is enabled by default. For manual setups, set this environment variable in both your backend and dashboard `.env` files:
88180

89181
```
90182
NEXT_PUBLIC_STACK_IS_LOCAL_EMULATOR=true

0 commit comments

Comments
 (0)