Installation

This guide takes you from a fresh download to a running application. The entire process is automated — a single make install command handles dependency installation, database setup, and service startup.

Prerequisites

You need two tools installed on your machine:

You do not need PHP, Node.js, Composer, or pnpm installed on your host machine. Everything runs inside Docker containers.

Download and Extract

After your purchase, you receive the source code as a .zip archive. You can download it from:

• The download link in your purchase confirmation email, or
• Your LemonSqueezy customer dashboard

Extract the archive and navigate into the project directory:

unzip saas4builders.zip
cd saas4builders

git init && git add -A && git commit -m "Initial commit from SaaS4Builders archive"

Run the Installer

make install

That's it. This single command handles the entire setup.

What make install Does

The installer runs these steps in order:

1. Copies environment files — Creates .env, backend/.env, and frontend/.env from their .example templates (skips if files already exist).
2. Installs Git hooks — Sets up pre-commit hooks for code formatting (requires a Git repository — see the tip above).
3. Builds Docker images — Runs docker compose build to build the PHP and Node containers from their Dockerfiles.
4. Starts all services — Runs docker compose up -d to start 9 containers in the background.
5. Waits for services — Pauses 10 seconds to let PostgreSQL and Redis initialize.
6. Installs PHP dependencies — Runs composer install inside the PHP container.
7. Generates application key — Runs php artisan key:generate to create the Laravel encryption key.
8. Runs migrations and seeds — Runs php artisan migrate --seed to create the database schema and populate it with demo data.
9. Installs Node dependencies — Runs pnpm install inside the Node container.

The entire process takes 3-10 minutes depending on your internet connection and machine speed.

Verify the Installation

Once make install completes, you should see:

✅ Setup complete!

🌐 Backend API: http://localhost:8000
🌐 Frontend:    http://localhost:3000
📧 Mailpit:     http://localhost:8025

Open these URLs to verify everything is running:

Additional services available for debugging:

Useful Commands

Here are the commands you will use most during development:

Run make help to see the full list of available commands.

Common Issues

Port Conflicts

If a port is already in use on your machine, the container using that port will fail to start. Edit the root .env file to change the conflicting port:

NGINX_PORT=8001          # Default: 8000
NUXT_PORT=3001           # Default: 3000
DB_PORT=5433             # Default: 5432
REDIS_PORT=6380          # Default: 6379
MAILPIT_UI_PORT=8026     # Default: 8025
REVERB_PORT=8081         # Default: 8080

Then restart the containers:

make restart

Containers Won't Start

Check the container logs for error messages:

make logs

Common causes:

• Docker is not running — start Docker Desktop or the Docker daemon.
• Insufficient disk space — Docker images require several GB of space.
• Previous containers still running — run make down first, then make up.

Permission Issues on Linux

The PHP container runs as user www with UID/GID 1000. If your host user has a different UID, you may see permission errors on mounted volumes. Ensure your host user's UID matches 1000, or adjust the Dockerfile in docker/php/Dockerfile.

Database Connection Errors

If migrations fail with a connection error, the PostgreSQL container may not be ready yet. Wait a few seconds and retry:

make migrate

If the issue persists, check that the PostgreSQL container is healthy:

docker compose ps

The saas-postgres container should show healthy in its status.

Apple Silicon (M1/M2/M3/M4)

The Docker setup works natively on Apple Silicon. All images use Alpine or Slim variants that provide ARM64 support. No Rosetta emulation or special configuration is needed.

Slow First Build

The first make install downloads Docker images and builds custom containers. This can take 5-10 minutes on a slow connection. Subsequent starts (make up) are fast because images are cached locally.

Project Structure

After installation, your project looks like this:

saas4builders/
├── backend/              # Laravel 13 API
├── frontend/             # Nuxt 4 application
├── docker/               # Dockerfile and config for each service
│   ├── nginx/
│   ├── node/
│   ├── php/
│   └── postgres/
├── docs/                 # Internal documentation
├── .env                  # Docker Compose configuration
├── docker-compose.yml    # Service definitions
├── Makefile              # Development commands
└── CLAUDE.md             # AI agent context

The backend/ and frontend/ directories are independent projects. Each has its own dependencies, configuration, and test suite. They communicate exclusively through the REST API.

What's Next

• Docker Setup — Understand the 9 Docker services, how they connect, and how to customize them.
• Environment Configuration — Configure Stripe, mail, OAuth, and other services.
• Running the Demo — Explore the seeded demo data and walk through the application.