Local Setup

This guide will walk you through setting up saasbrella. We will go through the process of cloning the project, installing dependencies, setting up your database and running the local development server.

Start with GitHub Codespace

Recommended: saasbrella provides a 1-click setup experience with GitHub Codespaces. This is the fastest and easiest way to get started with local development.

How it works

When you accept the repository invite for your saasbrella project, you’ll have access to a pre-configured GitHub Codespace that includes:

  • All dependencies installed - Node.js, Wasp, Docker, and all required packages are automatically set up
  • Running database - PostgreSQL database is pre-configured and running
  • Local Wasp app - Your application is ready to run with wasp start
  • Pre-installed extensions - Claude Code extension is already installed for AI-assisted development

Simply go to your saasbrella user dashboard, navigate to your project settings, and click the “Open in Codespace” button. You’ll have a fully functional development environment in your browser within minutes. No local setup required!

If you prefer to set up locally on your machine, continue with the prerequisites and setup steps below.

Prerequisites

Before you can get started, you will need to have the following installed on your machine.

Installing Wasp 0.17.0

Linux / macOS / WSL (Windows)

Open your terminal and run:

Terminal window
curl -sSL https://get.wasp.sh/installer.sh | sh -s -- --version 0.17.0

Note for macOS with Apple Silicon (M1/M2/M3): If you encounter a “Bad CPU type in executable” error, you’ll need to install Rosetta:

Terminal window
softwareupdate --install-rosetta

Windows

Wasp doesn’t fully work on native Windows yet. The recommended approach is to use WSL (Windows Subsystem for Linux):

  1. Install WSL - Follow the WSL installation guide
  2. Install Ubuntu on WSL - Use the Microsoft Store or run: wsl --install -d Ubuntu
  3. Open Ubuntu terminal and follow the Linux instructions above

Important: Make sure your Wasp project is on the Linux file system (e.g., /home/username/projects/), not on the Windows file system (e.g., /mnt/c/Users/...), as WSL2 has issues detecting file changes on Windows drives.

Installing Node.js ≥22.12

We recommend using nvm (Node Version Manager) to install and manage Node.js versions:

Install nvm

Linux / macOS / WSL:

Terminal window
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Windows (PowerShell):

Terminal window
iwr -useb https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | iex

Install Node.js 22.12 or later

Terminal window
nvm install 22
nvm use 22

Verify the installation:

Terminal window
node -v  # Should show v22.12.0 or higher

Installing Docker

Linux

Terminal window
# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh


# Add your user to the docker group (optional, to run without sudo)
sudo usermod -aG docker $USER

macOS

Download and install Docker Desktop for Mac.

Windows

Download and install Docker Desktop for Windows. If you’re using WSL, you can also install Docker in your WSL environment following the Linux instructions.

Installing Git

Linux

Terminal window
# Ubuntu/Debian
sudo apt update
sudo apt install git


# Verify installation
git --version

macOS

Git is typically pre-installed on macOS. If not, install it via Homebrew:

Terminal window
brew install git

Or download from git-scm.com.

Windows

Download and install Git from git-scm.com. If you’re using WSL, Git is usually pre-installed, but you can install it manually:

Terminal window
sudo apt update
sudo apt install git

Configure Git (first time setup)

After installing Git, configure your name and email:

Terminal window
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Project setup

  1. Clone the repository

    Clone your saasbrella project repository. The repository name is an 8-character string provided when you create your project.

    Terminal window
    git clone https://github.com/saasbrella/[repoName].git
    cd [repoName]

    Replace [repoName] with your actual 8-character repository name. For example:

    Terminal window
    git clone https://github.com/saasbrella/a1b2c3d4.git
    cd a1b2c3d4

    Navigate to the app directory

    The Wasp application is located in the app directory. Change into it:

    Terminal window
    cd app

  2. Start the database

    saasbrella uses PostgreSQL as the database. Start the database using Wasp:

    Terminal window
    wasp db start

    This will start a PostgreSQL database in a Docker container. The database will be available at localhost:5432.

  3. Start the development server

    Once the database is running, start the Wasp development server:

    Terminal window
    wasp start

    This will:

    • Install all dependencies
    • Run database migrations
    • Start both the frontend and backend servers

    Your application will be available at http://localhost:3000.

Pushing Changes to Production

Once you’ve made changes to your application, you can push them to production using Git. saasbrella automatically deploys your changes when you push to the main branch.

Git Workflow

1. Stage your changes

Add all modified files to the staging area:

Terminal window
git add .

This command stages all changes in your working directory. You can also stage specific files:

Terminal window
git add path/to/specific/file.ts

2. Commit your changes

Create a commit with a descriptive message:

Terminal window
git commit -m "Your commit message describing the changes"

Good commit messages are clear and concise. For example:

  • "Add user authentication feature"
  • "Fix database connection issue"
  • "Update styling for dashboard page"

3. Push to production

Push your committed changes to the remote repository:

Terminal window
git push

This will push your changes to the main branch, which triggers an automatic deployment. Your changes will be live in production shortly after the push completes.

Complete workflow example:

Terminal window
# Make your code changes, then:
git add .
git commit -m "Add new feature"
git push

Note: Make sure you’re in the repository root directory (not the app directory) when running Git commands.

Troubleshooting

If you encounter any issues during setup, here are some common solutions:

Wasp not found after installation

After installing Wasp, you may need to restart your terminal or add Wasp to your PATH. The installer typically adds Wasp to ~/.local/bin. You can verify the installation by running:

Terminal window
wasp version

If Wasp is not found, add it to your PATH:

Terminal window
export PATH=$PATH:$HOME/.local/bin

Database connection issues

If wasp db start fails, make sure Docker is running:

Terminal window
docker ps

If Docker is not running, start Docker Desktop (macOS/Windows) or the Docker service (Linux).

Port already in use

If port 3000 is already in use, Wasp will automatically try the next available port. Check the terminal output for the actual URL.

File change detection issues (WSL2)

If you’re using WSL2 and file changes aren’t being detected, make sure your project is on the Linux file system (e.g., /home/username/projects/), not on the Windows file system (/mnt/c/Users/...).

Clean and restart

If you encounter persistent issues, try cleaning the Wasp build cache:

Terminal window
wasp clean
wasp db start
wasp start