Skip to main content

​
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 higherCheck your version:
php --version

Composer

Latest versionPackage manager for PHP:
composer --version

Node.js

Version 18 or higherRequired for frontend build:
node --version

PNPM

Latest versionFast 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="[email protected]"
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

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
Solution: Install PNPM globally:
npm install -g pnpm
Solution: Ensure storage and cache directories are writable:
chmod -R 775 storage bootstrap/cache
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us