Run Northstack locally

Open every terminal where the commands below expect it: inside northstack-full-stack for the full stack, or next to the app's folder for the Backend API package.

Open the terminal next to the app's folder, where you extracted the ZIP.

Start the API first: the dashboard reads all of its data from it, and the website's contact form and licence checkout call it.

Start the API

1. 01

   Install and configure

   .env.example works as it is on your own computer: SQLite in ./database.sqlite, the API on port 8000, and the website (http://localhost:3030) and the dashboard (http://localhost:3031) allowed to call it.

   TerminalCopy

   corepack enable
   cd back-end
   yarn install
   cp .env.example .env

   0:00 / 0:13

   Having trouble?

   I've done this step
2. 02

   Create the database

   yarn seed creates database.sqlite and its tables, the platform roles and settings, the sample workspace Forma Studio (12 projects with their boards, 8 members, 2 invitations, a Pro subscription with three invoices, an API key, the activity of the last weeks and three assistant conversations), a second workspace for its owner, and 732 organizations behind the platform figures. It finishes by printing the accounts to sign in with. Dates follow the day you seed. Running it again on a database that already has accounts adds no account or workspace and gives the built-in platform roles their permissions back.

   Terminalin back-endCopy

   yarn seed

   I've done this step
3. 03

   Start the server

   Terminalin back-endCopy

   yarn dev

   Expected result: localhost:8000/api/healthLocal answers with "status":"ok" and "database":"up".

   Having trouble?

   I've done this step

Start the API

1. 01

   Install and configure

   .env.example works as it is on your own computer: SQLite in ./database.sqlite, the API on port 8000, and the website (http://localhost:3030) and the dashboard (http://localhost:3031) allowed to call it.

   TerminalCopy

   corepack enable
   cd northstack-backend
   yarn install
   cp .env.example .env

   0:00 / 0:13

   Having trouble?

   I've done this step
2. 02

   Create the database

   yarn seed creates database.sqlite and its tables, the platform roles and settings, the sample workspace Forma Studio (12 projects with their boards, 8 members, 2 invitations, a Pro subscription with three invoices, an API key, the activity of the last weeks and three assistant conversations), a second workspace for its owner, and 732 organizations behind the platform figures. It finishes by printing the accounts to sign in with. Dates follow the day you seed. Running it again on a database that already has accounts adds no account or workspace and gives the built-in platform roles their permissions back.

   Terminalin northstack-backendCopy

   yarn seed

   I've done this step
3. 03

   Start the server

   Terminalin northstack-backendCopy

   yarn dev

   Expected result: localhost:8000/api/healthLocal answers with "status":"ok" and "database":"up".

   Having trouble?

   I've done this step

Every seeded account signs in with the password NorthstackDemo26!: owner@northstack.example, admin@northstack.example, member@northstack.example, billing@northstack.example, platform@northstack.example and support@northstack.example.

Start the workspace dashboard

In a second terminal:

1. 01

   Install and configure

   The copied .env points the dashboard at the API on port 8000 and its live permission updates on the same server.

   TerminalCopy

   cd dashboard
   yarn install
   cp .env.example .env

   0:00 / 0:09

   I've done this step
2. 02

   Start it and sign in

   Terminalin dashboardCopy

   yarn dev

   Expected result: localhost:3031Local opens the sign-in form. Sign in with owner@northstack.example and the password NorthstackDemo26!.

   Having trouble?

   I've done this step

Start the workspace dashboard

The API is not part of this package. On its own, the dashboard runs on its built-in sample data: start it without a .env file.

1. 01

   Install and start it on sample data

   With no .env, NEXT_PUBLIC_API_BASE_URL is empty and every screen answers from the sample data in your browser.

   TerminalCopy

   corepack enable
   cd northstack-dashboard
   yarn install
   yarn dev

   0:00 / 0:21

   Expected result: localhost:3031Local opens the sign-in form with a Sample data notice at the bottom. Any password signs in: owner@northstack.example opens the owner's workspace, and each seeded email opens its role.

   Having trouble?

   I've done this step
2. 02

   Connect it to the API

   With the Northstack API running on http://localhost:8000/api, stop yarn dev, copy the example settings and start it again. If your API runs somewhere else, set NEXT_PUBLIC_API_BASE_URL (with /api) and NEXT_PUBLIC_WEBSOCKET_BASE_URL (without it) in .env to its address.

   Terminalin northstack-dashboardCopy

   cp .env.example .env
   yarn dev

   Expected result: Sign in with owner@northstack.example and the password NorthstackDemo26!, which a seeded API accepts. The Sample data notice is gone.

   Having trouble?

   I've done this step

Start the public website

In a third terminal:

1. 01

   Install and configure

   Every value in the copied .env is optional: it points the website at the API on port 8000 and the dashboard on 3031.

   TerminalCopy

   cd website
   yarn install
   cp .env.example .env

   0:00 / 0:09

   I've done this step
2. 02

   Start it

   Terminalin websiteCopy

   yarn dev

   Expected result: localhost:3030Local opens the website in English; Arabic is at /ar.

   Having trouble?

   I've done this step

Start the public website

The API is not part of this package. On its own, the website runs on its built-in sample data: start it without a .env file.

1. 01

   Install and start it on sample data

   With no .env, NEXT_PUBLIC_API_BASE_URL is empty: the contact form and the licence checkout answer in your browser and send nothing.

   TerminalCopy

   corepack enable
   cd northstack-website
   yarn install
   yarn dev

   0:00 / 0:17

   Expected result: localhost:3030Local opens the website with a Sample data notice at the bottom of every page; Arabic is at /ar.

   Having trouble?

   I've done this step
2. 02

   Connect it to the API

   With the Northstack API running on http://localhost:8000/api, stop yarn dev, copy the example settings and start it again. If your API runs somewhere else, set NEXT_PUBLIC_API_BASE_URL in .env to its address, including /api.

   Terminalin northstack-websiteCopy

   cp .env.example .env
   yarn dev

   Expected result: The Sample data notice is gone, and the contact form and the checkout reach your API.

   Having trouble?

   I've done this step

Other ports

Without Docker the ports are set in the files. The website's dev and start scripts in package.json pass -p 3030; for another port run yarn next dev -p 3040 (or yarn next start -p 3040 after yarn build). The dashboard reads PORT from its .env (PORT=3041), and starts on 3031 without one. With the API, add a moved frontend's address to CORS_ORIGIN in the API's .env, and set it there as WEBSITE_URL for the website, or as DASHBOARD_URL and FRONTEND_URL for the dashboard; set the frontend's own NEXT_PUBLIC_SITE_URL or NEXT_PUBLIC_BASE_URL to match. To move the API, set PORT, PUBLIC_API_URL and PUBLIC_MEDIA_URL in its .env to the same number, and NEXT_PUBLIC_API_BASE_URL in both frontends (the dashboard's NEXT_PUBLIC_WEBSOCKET_BASE_URL too).

• A port is already in use

Production build

The same folders, built once and then started. First set the API's .env for production: with NODE_ENV=production the API never changes the tables on start, and it refuses to start while JWT_SECRET is empty or still the example value, or while CORS_ORIGIN is empty.

NODE_ENV=production
JWT_SECRET=paste-the-generated-secret-here
CORS_ORIGIN=http://localhost:3030,http://localhost:3031
FRONTEND_URL=http://localhost:3031
DASHBOARD_URL=http://localhost:3031
WEBSITE_URL=http://localhost:3030
PUBLIC_API_URL=http://localhost:8000
PUBLIC_MEDIA_URL=http://localhost:8000/media

Generate the secret with node -e "console.log(require('crypto').randomBytes(48).toString('hex'))". Then, in the API's folder, build it, create its tables once with the sample data, and start it. yarn seed:prod is the compiled yarn seed.

yarn build
yarn seed:prod
yarn start:prod

• Deploy it

Production build of the frontends

In each frontend's folder, stop yarn dev, build once and start. The website serves on 3030 and the dashboard on 3031.

yarn build
yarn start

The frontends compile their NEXT_PUBLIC_* values in at build time, so run yarn build again after changing .env. Before you deploy anywhere public, read the deployment guide.

• Deploy it

Start over with fresh demo data

Stop the API, then delete the database file and seed it again, in the API's folder. This deletes everything you created.

rm -f database.sqlite* && yarn seed

In PowerShell:

Remove-Item database.sqlite*; yarn seed

yarn reset empties every table and keeps them, and yarn drop drops every table; run yarn seed after either to fill the database again. On MySQL, where there is no file to delete, start over with:

yarn reset
yarn seed

Commands

Next

• Set your environment variables
• Run it with Docker instead
• Fix a setup problem