Skip to main content

Fresh project setup

You should follow this guide right after you initialize an empty repository with SaaS Boilerplate project. If you'd like to start with an already existing project, visit Launch exsting project


  • Install Docker
  • Install Node.js version 16.14 or above (which can be checked by running node -v). You can use nvm for managing multiple Node versions installed on a single machine.
  • Install Python version 3.8 (which can be checked by running python3 -v). You can use pyenv for managing multiple Python versions installed on a single machine.
  • Install pnpm version 7 or above (which can be checked by running pnpm --version)
  • Install nx version 15.4.5. After you install Node.js call npm install -g nx@15.4.5


  • Install PDM version 2.3 or above (which can be checked by running pdm --version)
    • you need this one if you want to run pdm install command in packages/backend or packages/workers outside docker container
  • Install AWS CLI version 2 (which can be checked by running aws --version)
    • you need this one if you want to deploy SaaS Boilerplate to AWS from your machine

Install dependencies

The project is configured to use pnpm workspaces, which means that you can install node_modules of all packages in repository, with single command:

pnpm install

Adjust .env.shared files

Root and almost all packages allow configuration through environmental variables. For local machine those need to be present in so called .env files. Those are of course ignored in GIT to avoid secret values being committed and shared with everyone. We prepared a set of defaults in form or .env.shared files located in the same directories that will be enough to run the project locally but a few need to be adjusted before you start the project for the first time.


Never store any secret values in those files!

.env.shared (in project root)
PROJECT_NAMEmyappThe name of your project (best if 3-5 characters to avoid AWS names being to long)
DJANGO_SECRET_KEYZs639zRcb5!9om2@tW2H6XG#Znj^TB^I50 character random string; docs
HASHID_FIELD_SALTt5$^r*xsMRXn1xjzhRSl8I5Hb3BUW$4U50 character random string; docs
ADMIN_EMAILadmin@exmaple.comWill be used to create first super admin user
ADMIN_DEFAULT_PASSWORDAvPZpabgj9Z8Will be used to create first super admin user

Start the app

Start backend

nx run core:docker-compose:up

or a shorter version:

make up

This will run docker containers for all the backend services, in the detached mode.

Backend is running on http://localhost:5001.

Admin Panel is running on http://admin.localhost:5001.

Workers trigger server is running on http://localhost:3005.

Mailcatcher is running on http://localhost:1080. Check dedicated doc before using.

Start webapp

nx start webapp

Web app is running on http://localhost:3000.

Start documentation

nx start docs

Docs app is running on http://localhost:3006.