Skip to the article
Aniq-UI

NorthstackRun Northstack locally

Run Northstack locally

Get your package running on your computer, with Docker.

For the Full Stack package

DockerRecommendedManual setup

Before you start: install and open Docker Desktop, or Docker Engine with Compose.

View requirements

  1. Download your template

    Open My templates and download the ZIP for your package.

    Expected result: A file named like northstack-full-stack-….zip is in your downloads.

  2. Unzip and open the folder

    Open a terminal where the ZIP is, extract it and move into the northstack-full-stack folder. On Windows, you can extract it in File Explorer instead, then open a terminal in the folder.

    Terminal
    unzip -q northstack-full-stack-*.zip
cd northstack-full-stack
ls

    Expected result: The folder lists back-end, dashboard, website and docker-compose.yml, beside README.md, QUICKSTART.md and LICENSE.md.

    Having trouble?

  3. Start the apps

    Build and start the API, the public website and the workspace dashboard. Nothing has to be configured first. The first start builds three images and fills the database with the sample workspaces, which takes a few minutes; later starts take seconds.

    Terminalin northstack-full-stack
    docker compose up --build

    A port is already in use?

    If the start stops with ports are not available, address already in use or port is already allocated, another program uses 3030, 3031 or 8000. Either stop it, or create a file named .env in the northstack-full-stack folder, beside docker-compose.yml, with the port you need, such as ADMIN_PORT=3041 (SITE_PORT for the website, API_PORT for the API). Run docker compose up --build again and open the app on its new port.

    A port is already in use

    Expected result: The three services keep running and the log stops scrolling. Leave this terminal open.

    Having trouble?

  4. Open the public website

    Open localhost:3030Local. English is at /en and Arabic at /ar. The website has no accounts of its own: its Live demo buttons open the dashboard's sign-in.

    Expected result: The website opens on its home page. The pricing page sells the two licences through the site's own checkout, which charges nobody until the API has payment keys.

    Having trouble?

  5. Sign in to the dashboard

    Open localhost:3031Local. Sign in with owner@northstack.example and the password NorthstackDemo26!. Every seeded account uses that password; change them before the stack is reachable from the internet.

    Expected result: The dashboard opens on Forma Studio's Workspace overview, with its projects, this month's usage, the project activity chart and the launch checklist.

    Having trouble?

Take a tour

What the sample workspace looks like once everything runs.

AccountEmailWhere
Owner of Forma Studio: every workspace page and action, billing, the roles matrix and deleting the workspace; also an admin of Monogramowner@northstack.exampleDashboard
Admin: projects, team and invitations, workspace settings, API keys and the activity log; the roles read only, no billingadmin@northstack.exampleDashboard
Member: projects and tasks, and the assistant; the team, the roles and the settings to read, no billingmember@northstack.exampleDashboard
Billing: the subscription, plan changes and invoices; the team, the roles and the settings to read; no projects (the overview leaves them out too) and no assistantbilling@northstack.exampleDashboard
Platform admin: every organization, user, staff member, platform role and settingplatform@northstack.exampleDashboard
Support: every platform page read only, and report exportssupport@northstack.exampleDashboard

Every account signs in with the password NorthstackDemo26!. These are local demo accounts only: on a server, start empty with SEED_SAMPLE_DATA=false and your own Platform admin (Starting empty).

The seed adds Forma Studio on the Pro plan, with 12 projects and their task boards, 8 members, 2 open invitations, three invoices, an API key, the activity of the last weeks and three past conversations with the assistant, and a second workspace, Monogram, that the owner switches to from the workspace switcher. Behind the platform administration there are 732 organizations in all, so every list and figure opens full. A new account made on the sign-up page goes through onboarding and creates its own workspace.

Stop and start again

Press Ctrl+C in the terminal to stop the apps, or run this from the northstack-full-stack folder. Your data, the database and the uploads, is kept in the northstack-data volume.

Terminalin northstack-full-stack
docker compose down

Start again with the same command as step 3. Without --build it reuses the images you already built.

Terminalin northstack-full-stack
docker compose up

Keep your data

docker compose down -v also deletes the data volume. The next start seeds a fresh copy of the sample workspaces, and everything you created is gone.

Run the public website

This package is the public website on its own. With no API it runs on its built-in sample data: the contact form and the licence checkout answer in your browser, and nothing is sent anywhere. To use the Northstack API instead, build it with the API's address. The API is a separate package and is not in this download.

  1. Download your template

    Open My templates and download the SaaS Website ZIP.

  2. Unzip and open the folder

    Terminal
    unzip -q northstack-website-*.zip
cd northstack-website
ls

    Expected result: The folder has a Dockerfile, a package.json and the QUICKSTART.md guide.

    Having trouble?

  3. Build the image

    On its own, with no API: the empty NEXT_PUBLIC_API_BASE_URL builds the site on its sample data.

    Terminalin northstack-website
    docker build -t northstack-website --build-arg NEXT_PUBLIC_API_BASE_URL= .

    With the Northstack API on http://localhost:8000/api and the dashboard on http://localhost:3031, build without arguments:

    Terminalin northstack-website
    docker build -t northstack-website .

    With your own API and domains, the NEXT_PUBLIC_* values are compiled into the JavaScript the browser loads, so they are build arguments:

    Terminalin northstack-website
    docker build -t northstack-website --build-arg NEXT_PUBLIC_SITE_URL=https://www.your-domain.com --build-arg NEXT_PUBLIC_API_BASE_URL=https://api.your-domain.com/api --build-arg NEXT_PUBLIC_DASHBOARD_URL=https://app.your-domain.com .
    Having trouble?

  4. Start it

    If port 3030 is taken, change the number on the left of -p, for example -p 3040:3030, and open that port instead. With an API, also build with NEXT_PUBLIC_SITE_URL=http://localhost:3040, and add that address to the API's CORS_ORIGIN and WEBSITE_URL.

    Terminalin northstack-website
    docker run -p 3030:3030 northstack-website

    Expected result: localhost:3030Local opens the website. English is at /en, Arabic at /ar. Built with no API, a Sample data notice at the bottom of every page says so.

    Having trouble?

With an API on your computer, inside the container localhost is the container itself. The browser still reaches the API, but for the checkout and its receipt to be complete when the server renders them, tell the website's server where the API is. --add-host makes host.docker.internal work on Linux; Docker Desktop already has it.

Terminalin northstack-website
docker run -p 3030:3030 -e API_INTERNAL_URL=http://host.docker.internal:8000/api --add-host=host.docker.internal:host-gateway northstack-website

Run the workspace dashboard

This package is the workspace dashboard on its own. With no API it runs on its built-in sample data in your browser, where any password signs in. To use the Northstack API instead, build it with the API's address. The API is a separate package and is not in this download.

  1. Download your template

    Open My templates and download the Workspace Dashboard ZIP.

  2. Unzip and open the folder

    Terminal
    unzip -q northstack-dashboard-*.zip
cd northstack-dashboard
ls

    Expected result: The folder has a Dockerfile, a package.json and the QUICKSTART.md guide.

    Having trouble?

  3. Build the image

    On its own, with no API: the empty NEXT_PUBLIC_API_BASE_URL builds the dashboard on its sample data.

    Terminalin northstack-dashboard
    docker build -t northstack-dashboard --build-arg NEXT_PUBLIC_API_BASE_URL= .

    With the Northstack API on http://localhost:8000/api (its live updates on http://localhost:8000) and the website on http://localhost:3030, build without arguments:

    Terminalin northstack-dashboard
    docker build -t northstack-dashboard .

    With your own API and domains, give the addresses the browser reaches them on:

    Terminalin northstack-dashboard
    docker build -t northstack-dashboard --build-arg NEXT_PUBLIC_API_BASE_URL=https://api.your-domain.com/api --build-arg NEXT_PUBLIC_BASE_URL=https://app.your-domain.com --build-arg NEXT_PUBLIC_WEBSITE_URL=https://www.your-domain.com .
    Having trouble?

  4. Start it and sign in

    If port 3031 is taken, change the number on the left of -p, for example -p 3041:3031, and open that port instead. With an API, also build with NEXT_PUBLIC_BASE_URL=http://localhost:3041, add that address to the API's CORS_ORIGIN, and set it as the API's DASHBOARD_URL and FRONTEND_URL.

    Terminalin northstack-dashboard
    docker run -p 3031:3031 northstack-dashboard

    Expected result: localhost:3031Local opens the sign-in form. On sample data any password signs in, and owner@northstack.example opens the owner's workspace. Against a seeded API, sign in with owner@northstack.example and the password NorthstackDemo26!.

    Having trouble?

Run the API

This package is the NestJS API on its own, on a SQLite file kept in a Docker volume, northstack-api-data, with the uploads. The public website and the workspace dashboard are separate packages and are not in this download.

  1. Download your template

    Open My templates and download the Backend API ZIP.

  2. Unzip and open the folder

    Terminal
    unzip -q northstack-backend-*.zip
cd northstack-backend
ls

    Expected result: The folder has a Dockerfile, a docker-entrypoint.sh, a package.json and the QUICKSTART.md guide.

    Having trouble?

  3. Build the image

    Terminalin northstack-backend
    docker build -t northstack-api .
    Having trouble?

  4. Start it with the sample data

    A new volume is seeded once with the sample workspaces and the accounts below, and every later start keeps what is there. On a server, start it empty instead with -e SEED_SAMPLE_DATA=false (Starting empty). If port 8000 is taken, change the number on the left of -p, for example -p 8010:8000, and add -e PUBLIC_API_URL=http://localhost:8010 -e PUBLIC_MEDIA_URL=http://localhost:8010/media so the links it writes (media, invoice downloads) use the new port too. Your frontends must then point at http://localhost:8010/api.

    Terminalin northstack-backend
    docker run -p 8000:8000 -v northstack-api-data:/data northstack-api

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

    Having trouble?

The seeded accounts are owner@northstack.example, admin@northstack.example, member@northstack.example, billing@northstack.example, platform@northstack.example and support@northstack.example, all with the password NorthstackDemo26!. Sign in with POST /api/auth/login, or from a Northstack dashboard.

The container accepts the website on http://localhost:3030 and the dashboard on http://localhost:3031. On other addresses, pass CORS_ORIGIN (both, comma separated), FRONTEND_URL and DASHBOARD_URL (the dashboard) and WEBSITE_URL (the website) with -e. Pass your keys the same way, only the ones you need:

Terminalin northstack-backend
docker run -p 8000:8000 -v northstack-api-data:/data -e GOOGLE_API_KEY=your-key northstack-api

Do not pass --env-file .env with a copy of .env.example: it sets NODE_ENV=development over the image's production default, which lets the API change the database schema by itself on every start. Without a JWT_SECRET of your own, or with the example one, the container generates a secret and keeps it in the volume, so sign-ins survive a restart.

To start over with fresh sample data, remove the container first (docker rm -f with its name), then delete the volume with docker volume rm northstack-api-data.

Next

Stuck on a step?

Find a fix before you start over.

Troubleshooting

Cookie Preferences

We use cookies to enhance your browsing experience, analyze site traffic, and personalize content. By clicking "Accept All", you consent to our use of cookies for analytics and personalized advertising.