Installation

Set up your development environment and install SaaS Starter Vue

Installation

Get SaaS Starter Vue up and running on your local machine by following these installation steps.

Prerequisites

Before you begin, ensure you have the following installed on your development machine:

PHP

Version 8.2 or higher

Check your version:

php --version

Composer

Latest version

Package manager for PHP:

composer --version

Node.js

Version 18 or higher

Required for frontend build:

node --version

PNPM

Latest version

Fast package manager:

pnpm --version

Database Requirement

SaaS Starter Vue is configured to use PostgreSQL by default. Make sure you have PostgreSQL installed and running.

# Check PostgreSQL is running
psql --version

If you don’t have PNPM installed, you can install it globally:

npm install -g pnpm

Installation Steps

1. Clone the Repository

   Clone the SaaS Starter Vue repository to your local machine:

   git clone https://github.com/zrclouddev-oss/saas-starter-vue.git
   cd saas-starter-vue
   
2. Configure Environment Variables

   Copy the example environment file and configure your settings:

   cp .env.example .env
   

   Open .env and configure your database connection:

   .env

   APP_NAME="SaaS Starter Vue"
   APP_ENV=local
   APP_DEBUG=true
   
   # Application URL Configuration
   APP_URL_BASE=saas-starter-vue.test
   APP_URL=http://${APP_URL_BASE}
   
   # Database Configuration
   DB_CONNECTION=pgsql
   DB_HOST=127.0.0.1
   DB_PORT=5432
   DB_DATABASE=your_database_name
   DB_USERNAME=your_username
   DB_PASSWORD=your_password
   
   # Queue Configuration
   QUEUE_CONNECTION=database
   
   # Mail Configuration
   MAIL_MAILER=smtp
   MAIL_HOST=127.0.0.1
   MAIL_PORT=2525
   MAIL_FROM_ADDRESS="[e-mail]"
   MAIL_FROM_NAME="${APP_NAME}"
   

   Make sure to create the PostgreSQL database before running migrations:

   createdb your_database_name
   
3. Run Automated Setup

   SaaS Starter Vue includes a convenient setup script that handles all installation tasks:

   composer run setup
   

   This command automatically:

   • Installs PHP dependencies via Composer
   • Generates application key
   • Runs database migrations (creates all tables)
   • Installs frontend dependencies via PNPM
   • Builds frontend assets

   The setup process may take a few minutes depending on your internet connection and system performance.

4. Verify Installation

   After setup completes, verify everything is installed correctly:

   # Check backend dependencies
   composer show
   
   # Check frontend dependencies
   pnpm list
   
   # Check database connection
   php artisan db:show
   

Manual Installation (Alternative)

If you prefer to run installation steps manually, or if the automated setup encounters issues:

1. Install Backend Dependencies

   composer install
   
2. Generate Application Key

   php artisan key:generate
   
3. Run Database Migrations

   php artisan migrate
   
4. Install Frontend Dependencies

   pnpm install
   
5. Build Frontend Assets

   pnpm run build
   

Configuration Details

Multi-Tenancy Setup

The application uses stancl/tenancy for multi-tenant architecture. Tenancy is automatically configured, and migrations create both central and tenant databases:

• Central Database: Stores system users, tenants, and plans
• Tenant Databases: Each tenant gets an isolated database schema

Tenant databases are created automatically when you create a new tenant through the admin dashboard.

Queue Configuration

By default, the application uses database queues:

.env

QUEUE_CONNECTION=database

Queues are required for:

• Sending emails (password resets, verifications)
• Tenant provisioning tasks
• Background processing

Session Configuration

Sessions are stored in the database for better scalability:

.env

SESSION_DRIVER=database
SESSION_LIFETIME=120

Development Tools

Code Quality Tools

The project includes several tools for maintaining code quality:

# PHP linting (Laravel Pint)
composer run lint

# Run tests
composer run test

# Frontend formatting (Prettier)
pnpm run format

# Frontend format check
pnpm run format:check

Troubleshooting

Common Issues

Database connection failed

Solution: Verify your PostgreSQL credentials in .env and ensure the database exists:

# Check if database exists
psql -U your_username -l

# Create database if needed
createdb your_database_name

PNPM not found

Solution: Install PNPM globally:

npm install -g pnpm

Permission denied errors

Solution: Ensure storage and cache directories are writable:

chmod -R 775 storage bootstrap/cache

Migration errors

Solution: Reset the database and run migrations again:

php artisan migrate:fresh

This will drop all tables and data. Only use in development!

Getting Help

If you encounter issues not covered here:

1. Check the GitHub Issues
2. Review Laravel 12 and Vue 3 documentation
3. Verify all prerequisites are correctly installed

Next Steps

Quick Start Guide

Now that installation is complete, follow the quickstart guide to run the application and create your first tenant.