Run existing project

This section provides instructions for running an existing project based on the ShipFast locally on your machine. To run an existing project, you will first need to have a cloned instance of the ShipFast project. Once you have it, you can follow the instructions in this section to install the necessary dependencies and start the application.

The section will include a list of requirements, such as the minimum version of Node.js. It will also provide step-by-step instructions for installing the dependencies.

Once the dependencies are installed, it will provide instructions for starting the application.

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.

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

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.