Run new project

Fresh project setup

This guide should be followed right after initializing an empty repository with ShipFast project. If you'd like to start with an already existing project, please visit Launch existing project.

Requirements

• Install Docker
• Install Node.js version 18 or above (which can be checked by running node -v).
  • You can use nvm or n for managing multiple Node versions installed on a single machine.
• Install pnpm version 8.6 or above (which can be checked by running pnpm --version)
• (Windows only) Install WSL 2

Optional

• Install Python version 3.11 (which can be checked by running python3 -v) and 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
  • You can use pyenv for managing multiple Python versions installed on a single machine.

Environment setup

Install dependencies

caution

If you are using a Windows machine, it's mandatory to have WSL 2 (Windows Subsystem for Linux) installed on your system to run the commands for installing dependencies and running the application.

Please follow the official guide for installing WSL 2 on Windows before proceeding. Failure to do so may result in issues during the installation process.

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

pnpm install

Adjust .env.shared files

Copy .env.shared to .env in the project root and ./packages/backend/.env.shared to ./packages/backend/.env and adjust the values to your needs.

caution

Never store any secret values in those files!

.env.shared (in project root)

Name	Example	Description
PROJECT_NAME	myapp	The name of your project (best if 3-5 characters to avoid AWS names being too long)

./packages/backend/.env.shared

Name	Example	Description
DJANGO_SECRET_KEY	Zs639zRcb5!9om2@tW2H6XG#Znj^TB^I	50-character random string; docs
HASHID_FIELD_SALT	t5$^r*xsMRXn1xjzhRSl8I5Hb3BUW$4U	50-character random string; docs
ADMIN_EMAIL	[email protected]	Will be used to create the first super admin user
ADMIN_DEFAULT_PASSWORD	AvPZpabgj9Z8	Will be used to create the first super admin user

Start the app

This section provides instructions for running the ShipFast locally on your machine. It covers three main areas: starting the local dev web server, starting the backend services using docker-compose, and (optionally) launching a local documentation instance based on Docusaurus.

caution

If you are using a Windows machine, it's mandatory to have WSL 2 (Windows Subsystem for Linux) installed on your system to run the commands for installing dependencies and running the application.

Please follow the official guide for installing WSL 2 on Windows before proceeding. Failure to do so may result in issues during the installation process.

Start backend

Project includes a set of backend services that can be run using docker-compose:

pnpm nx run core:docker-compose:up

or a shorter version:

pnpm shipfast 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 the dedicated doc before using.

Start webapp

To start the local development web server, you'll need to run a following command in your terminal:

pnpm nx start webapp

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

Start documentation

Finally, the ShipFast comes with a local documentation instance based on Docusaurus. This provides easy access to the documentation while you're working on your SaaS product, so you can quickly find answers to any questions you may have.

pnpm nx start docs

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

tip

Once you've successfully set up your project, you can check out the "Working with ShipFast" documentation to learn more about how to take advantage of the boilerplate's features and best practices.