Liberu Software — Laravel 13 SaaS Boilerplate

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

A production-ready SaaS starter built with Laravel 13, 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 13, PHP 8.5, Filament 5 and Livewire 4 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 uses a single, custom module system rooted at app/Modules/, under the app's own App\Modules\ PSR-4 namespace. There is no internachi/modular, no per-module composer.json/composer-merge-plugin, and no app-modules/ directory — none of that is used. Modules have a DB-backed lifecycle (install/enable/disable/uninstall) managed by ModuleManager, and an enabled module's Filament resources/pages/widgets are auto-discovered per panel by App\Filament\Plugins\ModuleFilamentPlugin. app/Modules/Blog/ is the reference implementation — copy its shape when adding a module.

Manage modules from /admin → Modules: the list shows every module discovered from disk with enable/disable/install/uninstall actions (backed by ModuleManager); there is no artisan module:* command.

Module Features

• PSR-4 under the existing App\ autoload — no per-module composer.json, no composer-merge-plugin, no internachi/modular/app-modules/.
• module.json (not composer.json) declares name, version, description, dependencies, and a config map.
• Lifecycle hooks — onInstall/onEnable/onDisable/onUninstall on your BaseModule subclass — each firing a Module{Installed,Enabled,Disabled,Uninstalled} event.
• Panel-targeted Filament auto-discovery: Filament/Admin/{Resources,Pages,Widgets} is discovered into the /admin panel, Filament/App/{Resources,Pages,Widgets} into /app (via ModuleFilamentPlugin::make()->for('Admin') / ->for('App'), registered on each panel).
• Enabled-gating: routes, views, and translations are only registered for modules the modules DB table marks enabled; config and migrations always load regardless of state.
• Dependency checks: enable()/install() refuse to run if a declared dependency isn't present and enabled.
• Admin UI: the Modules Filament resource (app/Filament/Resources/ModuleResource.php) lists modules and drives enable/disable/install/uninstall.

See docs/MODULE_DEVELOPMENT.md for a full walkthrough using Blog as the worked example.

Module Structure

app/Modules/Blog/
├── module.json                     # name, version, description, dependencies, config
├── BlogModule.php                  # main module class, extends BaseModule
├── Filament/
│   └── Admin/                      # discovered into the /admin panel
│       └── Resources/
│           ├── PostResource.php
│           └── PostResource/Pages/{ListPosts,CreatePost,EditPost}.php
│                                    # a Filament/App/ sibling would target the /app panel
├── Http/Controllers/BlogController.php
├── Models/Post.php
├── config/blog.php                 # config('blog.posts_per_page') — file named after the
│                                    # module merges at its own root key, not blog.blog.*
├── database/migrations/
│   └── 2026_07_01_000000_create_module_blog_posts_table.php
├── resources/views/index.blade.php # view('blog::index')
└── routes/web.php                  # blog.index route

Filament Integration

Each enabled module's Filament components are auto-discovered per panel:

• Filament/Admin/Resources|Pages|Widgets → registered into the /admin panel
• Filament/App/Resources|Pages|Widgets → registered into the /app panel
• Discovery is done by App\Filament\Plugins\ModuleFilamentPlugin, added to each panel's ->plugins([...]) in AdminPanelProvider/AppPanelProvider
• A resource whose model has no team() relationship (like Blog's Post) must override isScopedToTenant(): false, same as core resources on the tenant-scoped /admin panel

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 for custom layouts, CSS, and JavaScript per visual theme. Two themes ship ready to use:

• default — the stock look (loads resources/css/app.css); active out of the box, no visual change until you switch.
• clear-signal — a teal theme built from the DESIGN.md "Clear Signal" design system (teal palette + Inter). Its theme.json colors.primary: teal also drives the Filament admin/app panel accent when it's the active site theme.

A dark theme is also included as a reference.

Quick Start with Themes

Pick the site-wide theme in the admin panel: Site Settings → Appearance → Site Theme. Individual users can still override it.

Switch themes programmatically:

set_theme('clear-signal');  // Switch theme (session / user preference)
$current = active_theme();   // Get the active theme

Use the per-user theme switcher component:

<livewire:theme-switcher />

clear-signal ships a compiled Tailwind bundle, so it only restyles the frontend after npm run build. Before that (or for default/dark), the frontend safely falls back to resources/css/app.css.

Theme Features

• Per-theme Tailwind bundles - A theme can ship a self-contained Tailwind bundle at /themes/{theme}/css/app.css, wired into vite.config.js input. @themeVite loads the active theme's built bundle when it's in the Vite manifest, otherwise resources/css/app.css.
• Admin-selectable site theme - Choose the site-wide theme in Site Settings; per-user overrides supported.
• Custom Layouts - Theme-specific Blade layouts in /themes/{theme}/views/
• User Preferences - Themes saved to database per user or session
• Dynamic Switching - Switch themes on the fly with the Livewire component
• Fallback System - Falls back to resources/css/app.css / default files when a theme has no built bundle or custom file
• Blade Directives - @themeVite (load the active theme's frontend bundle), @themeCss, @themeJs, @themeAsset(), @themeLayout()

Using Themes in Views

<head>
    {{-- Load the active theme's built bundle (or app.css fallback) + app.js --}}
    @themeVite
</head>

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

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

@themeVite is the frontend entry point. @themeCss/@themeJs remain available for layouts that load a theme bundle alongside app.css (both are gated on the Vite manifest, so they emit nothing until the assets are built).

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 (set colors.primary to a Tailwind color name — e.g. teal — to also drive the Filament panel accent).
3. Create the Tailwind bundle themes/mytheme/css/app.css (@import 'tailwindcss' + your @theme tokens) and any custom layout files.
4. Wire the bundle into vite.config.js — add 'themes/mytheme/css/app.css' to the Laravel plugin input array.
5. Build assets: npm run build. The theme is then selectable site-wide in Site Settings (themes are auto-discovered from themes/).

Documentation

• Theme System Guide - Complete guide for creating and using themes
• Example themes: themes/default/, themes/clear-signal/ (teal, with a compiled Tailwind bundle), 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.