Quick Start

Get a working multi-tenant SaaS application running in minutes

Quick Start Guide

This guide will walk you through starting the development server, logging in, and creating your first tenant.

Before starting, make sure you’ve completed the installation steps.

Start the Development Server

SaaS Starter Vue includes a convenient development command that starts all necessary services:

composer run dev

This command uses concurrently to run three services simultaneously:

Laravel Server

PHP development server on port 8000

Queue Worker

Processes background jobs and emails

Vite Dev Server

Hot module replacement for frontend

You should see output similar to:

[server] Starting Laravel development server: http://127.0.0.1:8000
[queue]  Processing jobs from database queue...
[vite]   VITE v7.0.4 ready in 1234 ms
[vite]   ➜ Local: http://localhost:5173/

By default, the application will be available at http://saas-starter-vue.test or http://localhost:8000 depending on your .env configuration.

Create Your First Admin User

Since this is a fresh installation, you’ll need to create an admin user to access the system dashboard.

1. Access Registration Page

   Navigate to the registration page:

   http://saas-starter-vue.test/auth/register
   

   Or click “Register” from the login page.

2. Fill Registration Form

   Enter your admin user details:

   • Name: Your full name
   • Email: Your email address
   • Password: A secure password (minimum 8 characters)
   • Confirm Password: Re-enter your password

   Click Register to create your account.

3. Verify Email (Optional)

   If email verification is enabled, check your email inbox for a verification link.

   In development, emails are logged. Check storage/logs/laravel.log or configure a mail testing service like Mailtrap.

Access the Dashboard

After registration and login, you’ll be redirected to the system dashboard:

http://saas-starter-vue.test/dashboard

The dashboard provides an overview of:

• Total tenants
• Active subscriptions
• Trial accounts
• Canceled tenants

The dashboard will initially show zero tenants since this is a fresh installation.

Create Your First Tenant

Now let’s create your first tenant (customer account) in the multi-tenant system.

1. Navigate to Tenants Page

   From the dashboard, click Tenants in the navigation menu, or navigate to:

   http://saas-starter-vue.test/tenants
   
2. Click Create Tenant

   Click the “Create Tenant” or ”+” button to open the tenant creation form.

3. Fill Tenant Information

   Enter the tenant details:

   {
     "name": "Acme Corporation",
     "domain": "acme",          // Subdomain for tenant
     "email": "[e-mail]",  // Tenant admin email
     "plan_id": 1,               // Select a subscription plan
     "status": "Active"          // Tenant status
   }
   

   The domain must be unique and will be used as a subdomain: acme.saas-starter-vue.test

4. Submit Form

   Click Create or Save. The system will:

   • Create the tenant record in the central database
   • Provision a new isolated database schema
   • Configure the subdomain routing
   • Run tenant-specific migrations

   You’ll see a success message:

   ✓ Tenant created successfully! Database and domain configured.
   

View Tenant Dashboard

Once created, your tenant will appear in the tenants list with key information:

Tenant Data Structure

{
  id: 1,
  name: "Acme Corporation",
  domain: "acme",
  email: "[e-mail]",
  status: "Active",
  plan: {
    name: "Professional",
    price: "$49.00"
  },
  created_at: "2026-03-06T10:30:00.000000Z"
}

{
  "total": 1,
  "active": 1,
  "trial": 0,
  "canceled": 0
}

Manage Tenants

From the tenants page (/tenants), you can perform various management operations:

Update Tenant

Click the Edit icon to modify tenant details:

• Change plan subscription
• Update contact information
• Modify status

Cancel Tenant

Click the Cancel button to initiate a 30-day grace period:

POST /tenants/{tenant}/cancel

During the grace period:

• Tenant status changes to “Canceled”
• Data is retained for 30 days
• Tenant can be restored

Restore Tenant

For canceled tenants within the grace period:

POST /tenants/{tenant}/restore

This reactivates the tenant and restores full access.

Delete Tenant

Permanently delete a tenant and all associated data:

DELETE /tenants/{tenant}

This action is irreversible and will:

• Delete the tenant’s database schema
• Remove all domain configurations
• Permanently erase all tenant data

Create Subscription Plans

Before creating many tenants, you’ll want to set up subscription plans:

1. Navigate to Plans

   Click Plans in the navigation menu or go to:

   http://saas-starter-vue.test/plans
   
2. Create a Plan

   Click Create Plan and fill in the details:

   {
     "name": "Professional",
     "description": "Perfect for growing teams",
     "price": 49.00,
     "currency": "USD",
     "billing_period": "monthly",
     "features": [
       "Unlimited users",
       "Advanced analytics",
       "Priority support"
     ],
     "is_active": true
   }
   
3. Assign to Tenants

   When creating new tenants, select from your available plans to automatically configure billing and feature access.

Enable Two-Factor Authentication

Secure your admin account with 2FA:

1. Go to Settings

   Click your profile avatar and select Settings, or navigate to:

   http://saas-starter-vue.test/settings/security
   
2. Enable 2FA

   In the Security section:

   1. Click Enable Two-Factor Authentication
   2. Scan the QR code with your authenticator app (Google Authenticator, Authy, etc.)
   3. Enter the 6-digit code to confirm
   4. Save your recovery codes in a secure location
3. Test 2FA

   Log out and log back in. You’ll now be prompted for a 2FA code after entering your password.

Working with the Queue System

Many operations run in the background via queues:

Monitor Queue Jobs

The composer run dev command automatically starts a queue worker. To monitor queue jobs:

# View queue status
php artisan queue:work --verbose

# View failed jobs
php artisan queue:failed

# Retry failed jobs
php artisan queue:retry all

Common Queued Operations

• Email notifications (password resets, verifications)
• Tenant database provisioning
• Subscription billing updates
• Export operations

In production, you should use a proper queue driver like Redis or Amazon SQS instead of the database driver.

Development Workflow

Hot Module Replacement (HMR)

With Vite running, your frontend updates automatically:

# Edit any Vue component
/resources/js/pages/system/Dashboard.vue

# Changes appear instantly in browser

Backend Changes

For backend changes, the Laravel development server automatically reloads:

# Edit controller
/app/Http/Controllers/System/TenantController.php

# Refresh browser to see changes

Database Changes

When modifying database schema:

# Create migration
php artisan make:migration add_feature_to_tenants

# Run migration
php artisan migrate

# For tenant-specific tables
php artisan tenants:migrate

Next Steps

Now that you have a working SaaS application, explore these areas:

Customize Tenant Features

Add custom functionality specific to your SaaS product

Configure Email

Set up SMTP or email service for transactional emails

Build Tenant UI

Create the customer-facing application interface

Set Up Payments

Integrate Stripe or another payment processor

Useful Commands Reference

Development

# Start all dev services
composer run dev

# Run frontend only
pnpm run dev

# Run backend only
php artisan serve

# Watch queue jobs
php artisan queue:work --verbose

# Run migrations
php artisan migrate

# Fresh install (drops all tables)
php artisan migrate:fresh

# Run tenant migrations
php artisan tenants:migrate

# Check database status
php artisan db:show

# Lint PHP code
composer run lint

# Run tests
composer run test

# Format frontend code
pnpm run format

Keep the development server running while you work. All three services (Laravel, Queue, Vite) need to be active for the full development experience.