mirror of
https://github.com/stack-auth/stack.git
synced 2026-06-04 21:04:37 +08:00
748d708d53
## Summary Refreshes the docs around Stack Auth setup, CLI workflows, local development, the local emulator, known SDK errors, self-hosting, and the public showcase. This also wires the new docs into Mintlify navigation and normalizes `sharp` dependency resolution for docs/image tooling. Base: `dev` -> Head: `docs-mintlify/updates` Scope: 17 files, +1154 / -435 ## What's New - Adds a dedicated **Stack CLI** guide covering install, auth, init modes, project commands, config pull/push, `stack exec`, and emulator commands. - Adds a full **Local Emulator** guide for QEMU requirements, ports, default credentials, config-file backed projects, image pulls, state, and troubleshooting. - Reworks **Local Development** around two supported workflows: cloud-backed local dev and emulator-backed local dev, including app env vars, local config files, CI usage, and common failure modes. - Rewrites **Self-host** around the supported `stackauth/server` Docker deployment path, including Postgres, ClickHouse, cron scheduling, seeded admin access, reverse proxy setup, SDK env vars, email, webhooks, S3 storage, upgrades, and common issues. - Adds a **Known Errors** reference for public SDK-exposed known errors, runtime `errorCode` values, and REST API handling. - Clarifies **CLI App Authentication** so users can distinguish authenticating their own CLI app from using the official `stack` command. - Updates the JWT guide to remove the missing inline viewer reference and recommend an external JWT viewer. - Adds showcase cards for Browser Use and Overworld with supporting images and styles. - Pins `sharp` to `0.34.5` through pnpm overrides and lockfile cleanup. ## Review Notes - The self-host guide was audited against the current Docker entrypoint, server env templates, seed script, ClickHouse migration behavior, cron endpoints, and SDK API URL env resolution. - The Docker image starts the backend and dashboard, but not production schedulers, so the new cron section is called out explicitly. - Managed Domain email setup is documented as operator-managed because it depends on server-side Resend/DNSimple credentials; self-hosters are directed toward Custom SMTP or their own Resend API key. - `self-host-old.mdx` is kept as a legacy reference file and is not added to navigation. - `emulator run` documentation now matches CLI behavior: it stops the emulator only when it started that emulator instance. ## Test Plan - [x] Reviewed all files changed by `origin/dev...HEAD`. - [x] Ran `git diff --check origin/dev...HEAD`. - [x] Checked IDE diagnostics for the changed docs/CLI files. - [ ] Preview Mintlify docs locally and click through new navigation entries. - [ ] Verify showcase cards and images in light and dark themes. - [ ] Smoke-test the copied self-host commands in a non-production Docker environment. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added comprehensive Stack CLI, Local Emulator, Known Errors, and Local Development guides * Restructured Self-Hosting guide for production deployments and expanded authentication docs * Updated site navigation to include new guide pages * **New Features** * Added visual showcase section with responsive cards and hover/zoom interactions (and supporting styles) <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|---|---|---|
| .. | ||
| api | ||
| guides | ||
| images | ||
| openapi | ||
| sdk | ||
| snippets | ||
| .gitignore | ||
| apps-sidebar-filter.js | ||
| docs.json | ||
| index.mdx | ||
| package.json | ||
| README.md | ||
| style.css | ||
docs-mintlify
How to run the Mintlify docs preview locally from this repository.
Prerequisites
-
Node.js
>=20.17.0 -
pnpm -
Repository dependencies installed (
pnpm installfrom repo root) -
OpenAPI specs in
openapi/are committed to git. Hosted Mintlify cannot run monorepo codegen on deploy, so these files must be present in the repo for production docs.When you change API route OpenAPI metadata, regenerate and commit the four specs from the repo root:
pnpm run --filter @stackframe/backend codegen-docs git add docs-mintlify/openapi/That writes
client.json,server.json,admin.json, andwebhooks.jsonintodocs-mintlify/openapi/(and intodocs/openapi/for the legacy Fumadocs app). CI fails ifpnpm codegenproduces different output than what is committed (see root lint-and-build workflow).
Run locally
From the repository root:
pnpm -C docs-mintlify run dev
This starts Mintlify in docs-mintlify on http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}04 (for example, http://localhost:8104 with the default prefix).
From inside docs-mintlify, you can also run:
pnpm dev
Useful variants:
# Override the default port
pnpm -C docs-mintlify run dev -- --port 3333
# Skip OpenAPI processing for faster iteration
pnpm -C docs-mintlify run dev -- --disable-openapi
Search + assistant in local preview
If you want local search and the Mintlify assistant:
pnpm -C docs-mintlify run login
pnpm -C docs-mintlify run status
Then re-run pnpm -C docs-mintlify run dev.
Package scripts
From repo root:
pnpm -C docs-mintlify run lint
pnpm -C docs-mintlify run typecheck
pnpm -C docs-mintlify run build
pnpm -C docs-mintlify run clean
lint runs both mint validate and mint broken-links.