Liberu Software — Laravel 12 SaaS Boilerplate

Build modern SaaS applications faster — a production-ready Laravel 12 boilerplate powered by PHP 8.5, Filament 5 and Livewire 4.

A production-ready SaaS starter built with Laravel 12, PHP 8.5, Filament 5, Livewire 4, Jetstream and Socialite — designed to kickstart multi-tenant or single-tenant SaaS applications with minimal setup.

Website: https://www.liberu.co.uk

---

Table of contents

• Overview
• Key features
• Prerequisites
• Standard (local) install
• Automated installation script
• Web-based graphical installer
• Docker / Sail install
• Running tests
• Troubleshooting
• Contributing
• License

---

Overview

Liberu Software is an open-source initiative that combines the latest versions of Laravel, PHP, Filament and Livewire to provide a solid, extensible foundation for modern web applications. This boilerplate ships with the common SaaS building blocks you need — authentication, an admin panel, real-time interactivity, social login, notifications, multi-language support and more — so you can focus on building your product rather than reinventing the wheel.

Whether you are starting a new SaaS product, an internal tool, or a modular enterprise application, this boilerplate is designed to get you productive from day one. It follows Laravel best practices, supports both single-tenant and multi-tenant patterns, and is fully containerised for Docker or Kubernetes deployments.

Private Messaging System — a complete secure messaging feature is built in, allowing users to exchange end-to-end encrypted messages. See MESSAGING.md and SETUP_MESSAGING.md for full documentation.

Multi-Language Support — the application supports English, Spanish, French and German out of the box with automated translations, smart language detection and per-user preferences. See docs/MULTI_LANGUAGE.md for details.

Key features

• Jetstream authentication and user profiles with avatar uploads
• Filament admin panel for resource management
• Livewire-powered UI for reactive components
• Social login via Socialite
• Real-time notifications with Pusher/Laravel Echo (see docs/NOTIFICATIONS.md)
• Modular architecture for easy custom module integration
• Custom Theme System - Support for custom layouts, CSS, and JS per theme (see docs/THEME_SYSTEM.md)
• Private Messaging System - Secure end-to-end encrypted messaging between users
• Multi-Language Support - Automated translations with language detection and user preferences (see docs/MULTI_LANGUAGE.md)
• Database seeders and example data (optional)
• Docker and Laravel Sail support for containerized development

Prerequisites

• PHP 8.5
• Composer
• Node.js (recommended: LTS) and npm or yarn (for front-end assets)
• MySQL / PostgreSQL or another supported DB
• Docker (if using Docker or Sail)

Standard (local) install

Quickstart: The fastest way to get started is to use the bundled install.sh script (see Automated installation script below) or the browser-based graphical installer at public/installer.php. Both options guide you step-by-step without requiring manual configuration.

These steps assume you want to run the application on your machine (not in Docker). They are intentionally clear and safe — back up any existing .env before overriding.

1. Clone the repo

   git clone https://github.com/liberusoftware/boilerplate-laravel.git
   cd boilerplate-laravel

2. Install PHP dependencies

   composer install

3. Copy the example env and configure

   cp .env.example .env
   # Edit .env to set DB_*, APP_URL and other settings

4. Generate application key

   php artisan key:generate

5. Install front-end dependencies (if you plan to build assets)

   npm install
   # or
   yarn

6. Build front-end assets (development or production)

   npm run dev   # development
   npm run build # production

7. Run migrations and seeders

   • IMPORTANT: Seeders will add example data. Skip seeding if you don't want that.

   php artisan migrate
   # When you want seed data:
   php artisan migrate --seed

8. Create storage symlink (required for profile photos)

   php artisan storage:link

9. Run the application

   php artisan serve --host=127.0.0.1 --port=8000

   Open: http://127.0.0.1:8000 (or your configured APP_URL)

Automated installation script

The repository includes install.sh, an interactive shell script that automates the entire setup process. Run it from the command line after cloning:

chmod +x install.sh
./install.sh

The script supports three installation modes:

1. Standalone - Local development/production installation
2. Docker - Containerised deployment
3. Kubernetes - K8s cluster deployment

Features of install.sh:

• Automatically detects and handles missing dependencies
• Downloads composer.phar if the composer command is not available
• Skips composer install if the vendor/ folder already exists
• Skips npm install if the node_modules/ folder already exists
• Provides coloured output and error checking
• Interactive prompts guide you through configuration step by step

Web-based graphical installer

A browser-based graphical installer is available at public/installer.php for users who prefer a point-and-click setup experience. Enable it before use:

INSTALLER_ENABLED=true
INSTALLER_KEY=your-secret-key   # optional: restrict access

The graphical installer provides:

• Step-by-step installation workflow with visual progress indicators
• Composer and NPM installation with automatic skip if already installed
• Fallback to download composer.phar if the composer command is not found
• Database configuration and connectivity testing
• Migration and seeding
• User creation with role assignment
• Module management (list, install, enable modules)
• "Run All Steps" button for fully automated one-click installation

Important: Disable the installer after setup by setting INSTALLER_ENABLED=false in .env.

Notes

• Configure mail and social provider settings in .env for production use.
• If you use a different DB (e.g., PostgreSQL), update .env accordingly.

Docker install

Two recommended Docker approaches are provided: manual Docker image and Laravel Sail.

A. Using the repository Dockerfile (image build)

1. Build the image from the project root:

   docker build -t boilerplate-laravel .

2. Create an env file for the container or use your .env:

   # Ensure .env contains correct DB and APP_URL values

3. Run the container (example: mapped port 8000):

   docker run --name boilerplate-app --env-file .env -p 8000:8000 -d boilerplate-laravel

4. Run migrations inside the running container:

   docker exec -it boilerplate-app php artisan migrate --seed
   docker exec -it boilerplate-app php artisan storage:link

5. Visit: http://localhost:8000

Notes for Docker image:

• When building a standalone image, ensure your Dockerfile handles running queue workers, scheduler, and any entrypoint tasks you need. For development, using docker run with volume mounts can be more convenient.

B. Recommended: Use Laravel Sail (Docker Compose wrapper)

1. Start Sail from project root:

   # Linux / macOS
   ./vendor/bin/sail up -d
   # Windows (PowerShell)
   vendor/bin/sail up -d

2. Run migrations and seeders using Sail:

   ./vendor/bin/sail artisan migrate --seed
   ./vendor/bin/sail artisan storage:link

3. Build front-end assets inside Sail (if needed):

   ./vendor/bin/sail npm install
   ./vendor/bin/sail npm run dev

4. Visit: http://localhost

Sail notes:

• Sail creates a complete development environment with services (DB, Redis, mailhog) and is the recommended containerized development workflow.

Running tests

This repository includes automated tests (see /tests). Run tests with:

# Local (uses Pest)
composer install --dev
vendor/bin/pest

# Or via Laravel's test runner which proxies to Pest
php artisan test

# With Sail
./vendor/bin/sail test

Troubleshooting

• "Permission denied" when running storage or bootstrap cache: adjust filesystem ownership

  sudo chown -R $USER:www-data storage bootstrap/cache
  chmod -R 775 storage bootstrap/cache

• DB connection errors: verify .env DB_* values and ensure the DB service is running (Sail or local).
• If assets not updating: clear caches

  php artisan config:clear
  php artisan cache:clear
  php artisan view:clear

Modular Architecture

This boilerplate features a powerful modular architecture based on the internachi/modular pattern, allowing you to easily create and integrate custom modules for specific project requirements. The system integrates seamlessly with Filament 5 and supports custom themes.

Quick Start with Modules

Create a new module:

php artisan make:module YourModule
# or
php artisan module create YourModule

Manage modules:

php artisan module list              # List all modules
php artisan module enable MyModule   # Enable a module
php artisan module disable MyModule  # Disable a module
php artisan module install MyModule  # Install a module (migrations + enable)
php artisan module info MyModule     # Show module information

Module Features

• Composer-based autoloading - Each module is autoloaded as a composer package
• Laravel package discovery - Automatic service provider registration
• Filament 5 integration - Auto-discovery of Filament resources, pages, and widgets
• Self-contained structure - Each module has its own controllers, models, views, routes, migrations, and configuration
• Lifecycle hooks - Enable, disable, install, and uninstall hooks for custom logic
• Dependency management - Declare dependencies on other modules
• Custom theme support - Modules can provide their own themes and assets
• Auto-discovery - Modules are automatically discovered and registered
• Configuration management - Easy configuration with dedicated config files
• Database migrations - Automatic migration running during installation
• Asset publishing - Assets are automatically published to public directory
• IDE-friendly - Full autocomplete and code navigation support

Documentation

• Module Development Guide - Comprehensive guide for developing custom modules
• Quick Start Guide - Get started with modules in minutes
• Example modules in app-modules/ and app/Modules/BlogModule/ - Reference implementations

Module Structure

app-modules/YourModule/
├── composer.json                  # Module composer configuration
├── src/
│   ├── YourModuleModule.php      # Main module class
│   ├── Providers/
│   │   └── YourModuleServiceProvider.php
│   ├── Http/Controllers/
│   ├── Models/
│   ├── Services/
│   ├── Filament/                 # Filament 5 resources (auto-discovered)
│   │   ├── Resources/
│   │   ├── Pages/
│   │   └── Widgets/
├── routes/
│   ├── web.php
│   ├── api.php
│   └── admin.php
├── database/migrations/
├── resources/
│   ├── views/
│   ├── lang/
│   └── assets/
└── tests/

Filament 5 Integration

Modules automatically integrate with Filament 5:

• Place Filament resources in src/Filament/Resources/
• Create custom pages in src/Filament/Pages/
• Add widgets in src/Filament/Widgets/
• All components are auto-discovered and registered

Custom Theme Support

Modules can provide custom themes:

• Define themes in resources/themes/
• Include custom layouts, CSS, and JavaScript
• Themes integrate with the application theme system
• Support for theme inheritance and overrides

Custom Theme System

This boilerplate includes a comprehensive theme system that allows you to create custom layouts, CSS, and JavaScript for different visual themes.

Quick Start with Themes

Switch themes programmatically:

set_theme('dark');  // Switch to dark theme
$current = active_theme();  // Get current theme

Use the theme switcher component:

<livewire:theme-switcher />

Theme Features

• Custom Layouts - Theme-specific Blade layouts in /themes/{theme}/views/
• Custom CSS - Theme-specific stylesheets in /themes/{theme}/css/app.css
• Custom JavaScript - Theme-specific scripts in /themes/{theme}/js/app.js
• User Preferences - Themes saved to database per user or session
• Dynamic Switching - Switch themes on the fly with Livewire component
• Fallback System - Automatically falls back to default files if theme doesn't have custom versions
• Blade Directives - @themeCss, @themeJs, @themeAsset(), @themeLayout()

Using Themes in Views

{{-- Use theme-specific layout --}}
@extends(theme_layout('app'))

@section('content')
    {{-- Include theme CSS and JS --}}
    @themeCss
    @themeJs
    
    {{-- Use theme assets --}}
    <img src="{{ theme_asset('images/logo.png') }}" alt="Logo">
@endsection

Creating a New Theme

1. Create theme directories:

mkdir -p themes/mytheme/views/layouts
mkdir -p themes/mytheme/css
mkdir -p themes/mytheme/js

2. Create theme.json with metadata
3. Create custom layout files
4. Create custom CSS and JS
5. Build assets: npm run build

Documentation

• Theme System Guide - Complete guide for creating and using themes
• Example themes: themes/default/ and themes/dark/

Theme Structure

themes/
└── mytheme/
    ├── theme.json           # Theme metadata
    ├── views/
    │   └── layouts/
    │       └── app.blade.php    # Custom layout
    ├── css/
    │   └── app.css              # Theme CSS
    └── js/
        └── app.js               # Theme JavaScript

Contributing

Contributions are welcome and warmly encouraged! To contribute:

1. Fork the repository on GitHub
2. Create a feature branch from main — e.g. git checkout -b feature/my-improvement
3. Make your changes and add or update tests where applicable
4. Ensure tests pass by running php artisan test or vendor/bin/pest
5. Commit with a clear, descriptive message
6. Open a Pull Request against the main branch — describe what you changed and why

Please follow the repository's code style. All pull requests are reviewed before merging. If you are planning a large change, consider opening an issue first to discuss it with the maintainers.

We welcome bug fixes, new features, documentation improvements and translations. Cross-repo collaboration with other Liberu projects is especially encouraged.

License

This project is licensed under the MIT License — see the LICENSE file for the full text.

The MIT license is one of the most permissive open-source licenses available. Key benefits:

• Free to use in personal, commercial and proprietary projects at no cost
• Free to modify — you can adapt the code to your needs without restriction
• Free to distribute — you may share, sell or sublicense the software
• No warranty obligations — you are not required to provide support or maintenance
• Patent peace — no hidden patent grants or restrictions
• Business-friendly — the only requirement is to retain the original copyright notice and license text

In short: take this boilerplate, build your product and ship it — the license will not get in your way.

Credits & Related Projects

• Liberu Software: https://www.liberu.co.uk

Related projects

The Liberu ecosystem contains a number of companion repositories and packages that extend or demonstrate functionality used in this boilerplate. Below is a concise, professional list of those projects with quick descriptions — follow the links to learn more or to contribute.

Project	Repository	Short description
Accounting	liberu-accounting/accounting-laravel	Accounting and invoicing features tailored for Laravel applications.
Automation	liberu-automation/automation-laravel	Automation tooling and workflow integrations for Laravel projects.
Billing	liberu-billing/billing-laravel	Subscription and billing management integrations (payments, invoices).
Boilerplate (core)	liberusoftware/boilerplate	Core starter and shared utilities used across Liberu projects.
Browser Game	liberu-browser-game/browser-game-laravel	Example Laravel-based browser game platform and mechanics.
CMS	liberu-cms/cms-laravel	Content management features and modular page administration.
Control Panel	liberu-control-panel/control-panel-laravel	Administration/control-panel components for managing services.
CRM	liberu-crm/crm-laravel	Customer relationship management features and integrations.
E‑commerce	liberu-ecommerce/ecommerce-laravel	E‑commerce storefront, product and order management.
Genealogy	liberu-genealogy/genealogy-laravel	Family tree and genealogy features built on Laravel.
Maintenance	liberu-maintenance/maintenance-laravel	Scheduling, tracking and reporting for maintenance tasks.
Real Estate	liberu-real-estate/real-estate-laravel	Property listings and real-estate management features.
Social Network	liberu-social-network/social-network-laravel	Social features, profiles, feeds and messaging for Laravel apps.

If you maintain or use one of these projects and would like a more detailed description or a different categorisation, open an issue or submit a pull request and we'll update the list. Contributions and cross-repo collaboration are warmly encouraged.