Requirements
What to install before you run your package, with Docker or without it.
For the Full Stack package
What each package contains
| Package | Apps in the download | Runs on its own |
|---|---|---|
| Full Stack | API, public website, workspace dashboard | Yes, all three together |
| SaaS Website | Public website | Yes, on its built-in sample data; the contact form and the licence checkout reach a Northstack API once you point it at one |
| Workspace Dashboard | Workspace dashboard | Yes, on its built-in sample data in the browser; real accounts and data need a Northstack API |
| Backend API | API | Yes, serving the API only |
A single-app package does not include the other apps. The API's code is only in the Full Stack and Backend API packages.
With Docker
- Docker Desktop on macOS or Windows, or Docker Engine with the Compose plugin on Linux, with Docker Compose 2.24 or newer, which every current Docker Desktop includes;
docker compose versionprints yours. The full stack starts with onedocker composecommand, anddocker-compose.ymlreadsback-end/.envonly when it exists, a setting older Compose versions reject. - An internet connection for the first build, which downloads the base images and the dependencies.
- Nothing else: Docker brings Node.js, and the database is a SQLite file inside a Docker volume.
With Docker
- Docker Desktop on macOS or Windows, or Docker Engine on Linux. Your app has its own
Dockerfile; Compose is not needed. - An internet connection for the first build, which downloads the base image and the dependencies.
Without Docker
- Node.js 22.13 or a later 22 release, or Node.js 24.11 or newer, for the API and the full stack (the API's
enginesis^22.13.0 || >=24.11.0). The website and the dashboard on their own run on Node.js 22.9 or newer. The Docker images run on Node.js 24. Check yours withnode -v. - Yarn 4, through Corepack. Run
corepack enableonce; each app pins Yarn 4.8.1 inpackageManagerand ships itsyarn.lock, soyarn installinstalls exactly the versions it was tested with. If your Node.js has no Corepack (Node.js 25 and newer leave it out), install it first withnpm install -g corepack. - No global packages.
Database
No database server. The API uses SQLite by default and yarn seed creates the file for you; Docker uses SQLite too. MySQL is supported as a configuration change, not a code change.
Ports
Each app listens on a fixed local port. Make sure nothing else uses them, or, with Docker, move one with SITE_PORT, ADMIN_PORT or API_PORT in a .env beside docker-compose.yml.
| App | Port |
|---|---|
| API | 8000 |
| Public website | 3030 |
| Workspace dashboard | 3031 |
Port
The website listens on port 3030. Connected to an API, it expects it on 8000 unless you give it another address. Make sure nothing else uses them.
Port
The dashboard listens on port 3031. Connected to an API, it expects it on 8000 unless you give it another address. Make sure nothing else uses them.
Port
The API listens on port 8000, and by default accepts the website from 3030 and the dashboard from 3031. Make sure nothing else uses port 8000.
An API to connect
Your app needs nothing else to start: with no API address it runs on its built-in sample data. To work with real accounts, payments and mail it needs the Northstack API, whose address you set in its .env or pass as a build argument. The API is sold as its own package, the Backend API, and is part of the Full Stack.
Optional services
None of these is needed to run Northstack locally. Each is switched on by its variables in the API's .env; a variable left empty keeps its feature off.
| Service | Without it |
|---|---|
| A Stripe account | Change plan on the dashboard's Billing page opens the built-in test checkout, and the website's licence checkout opens its own test checkout. Neither charges anybody, so both flows work end to end. |
| A PayPal REST app | PayPal on the licence checkout goes through the same test checkout. |
| An SMTP server for mail | Invitations, password resets and licence receipts are written to the API's log, links included, instead of being sent. |
| A Cloudflare R2 bucket | Project files and pictures are stored on the API's own disk (with Docker, in the data volume). |
| An AI key from Google Gemini, OpenAI or DeepSeek, any one | Each person can add their own key for a provider in the assistant, kept in their browser; without one the assistant cannot answer. Everything else works. |
| A key for the MCP server | POST /api/mcp refuses every request. |
Each paid service bills you on your own account with that provider. Northstack charges no tax by itself: set up tax for your country before taking real payments.