Installation

Lunar integrates into an existing Laravel application as a Composer package. This guide walks through the full setup process.

Requirements

PHP >= 8.3 (Lunar 1.5+) — PHP 8.2 is supported on Lunar 1.4 and earlier
Laravel 12, 13 (Lunar 1.5+) — Laravel 11 is supported on Lunar 1.4 and earlier
MySQL 8.0+ / PostgreSQL 9.4+
bcmath PHP extension
exif PHP extension
intl PHP extension

1. Install the package

composer require lunarphp/lunar:"^1.0" -W

2. Add the LunarUser trait

Parts of the Lunar core rely on the User model having certain e-commerce relationships (carts, orders, customers). Add the bundled trait and interface to any model that represents users in the application.

use Lunar\Base\Traits\LunarUser;
use Lunar\Base\LunarUser as LunarUserInterface;
// ...

class User extends Authenticatable implements LunarUserInterface
{
    use LunarUser;
    // ...
}

3. Register the admin panel

use Lunar\Admin\Support\Facades\LunarPanel;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        LunarPanel::register();
    }
}

4. Run the installer

php artisan lunar:install

The installer will guide through a series of prompts and perform the following:

Publish configuration files
Run database migrations
Create a default admin user
Seed initial data: a default channel, language, currency (USD), customer group, collection group, tax class, tax zone, and product/collection attributes
Publish Filament assets

5. Access the admin panel

Once the installer completes, the admin panel is available at https://<yoursite>/lunar.

Telemetry

Lunar sends anonymous usage data once per day to help the maintainers understand how Lunar is used. The data does not identify a store in any way. To opt out, add the following to a service provider’s boot method:

\Lunar\Facades\Telemetry::optOut();

Advanced installation options

Publish configuration before installing

The installer publishes configuration files automatically, but to customize settings before running php artisan lunar:install, publish them manually first:

php artisan vendor:publish --tag=lunar

The installer will detect the existing configuration and skip overwriting it.

Table prefix

Lunar prefixes all of its database tables to avoid conflicts. The default prefix is lunar_ and can be changed in config/lunar/database.php:

'table_prefix' => 'lunar_',

User ID field type

Lunar assumes the User model primary key is a BIGINT. If the application uses INT or UUID primary keys, update config/lunar/database.php before running migrations:

// Supported values: 'bigint', 'int', 'uuid'
'users_id_type' => 'bigint',

Disable bundled migrations

To take full control of Lunar’s database migrations, disable the bundled migrations and publish them into the application:

// config/lunar/database.php
'disable_migrations' => true,

php artisan vendor:publish --tag=lunar.migrations

What’s next?

Starter Kits

Get a head start with a pre-built Livewire or Inertia storefront.

Storefront Guides

Learn how to build a storefront from scratch with step-by-step guides.

System Settings

Configure channels, languages, currencies, and more.

Overview

Setup & Configuration

Starter Kits

Requirements

1. Install the package

2. Add the LunarUser trait

3. Register the admin panel

4. Run the installer

5. Access the admin panel

Telemetry

Advanced installation options

Publish configuration before installing

Table prefix

User ID field type

Disable bundled migrations

What’s next?

Starter Kits

Storefront Guides

System Settings

​Requirements

​1. Install the package

​2. Add the LunarUser trait

​3. Register the admin panel

​4. Run the installer

​5. Access the admin panel

​Telemetry

​Advanced installation options

​Publish configuration before installing

​Table prefix

​User ID field type

​Disable bundled migrations

​What’s next?

Starter Kits

Storefront Guides

System Settings

Requirements

1. Install the package

2. Add the LunarUser trait

3. Register the admin panel

4. Run the installer

5. Access the admin panel

Telemetry

Advanced installation options

Publish configuration before installing

Table prefix

User ID field type

Disable bundled migrations

What’s next?