# Capell install guide

This guide has two paths:

- **Path A:** a fresh Laravel app for a clean install.
- **Path B:** an existing Laravel app where you need to keep current users, routes, data, and deploy flow.

For the fastest demo, use the [quickstart](quickstart.md).

## Requirements

| Tool     | Supported versions                                                   |
| -------- | -------------------------------------------------------------------- |
| PHP      | 8.3+                                                                 |
| Laravel  | 11.44.2+, 12.x, or 13.x                                              |
| Filament | 4.7+ or 5.2+                                                         |
| Database | MySQL 8+, MariaDB 10.3+, SQLite, or your configured Laravel database |
| Node.js  | 20+                                                                  |
| Composer | 2.7+                                                                 |

Required PHP extensions: `fileinfo`, `intl`, `mbstring`, `openssl`, `curl`, `simplexml`, and either `gd` or `imagick`.

## Path A: fresh Laravel app

### 1. Create the app

```bash
composer create-project laravel/laravel music-store
cd music-store
cp .env.example .env
php artisan key:generate
```

Set your database values in `.env`, then confirm Laravel can boot:

```bash
php artisan about
```

### 2. Add Capell repositories

If your team installs Capell from private VCS repositories, add them before requiring packages:

```json
{
    "repositories": [
        { "type": "vcs", "url": "https://github.com/capell-app/core" },
        { "type": "vcs", "url": "https://github.com/capell-app/admin" },
        { "type": "vcs", "url": "https://github.com/capell-app/frontend" },
        { "type": "vcs", "url": "https://github.com/capell-app/marketplace" }
    ],
    "minimum-stability": "dev",
    "prefer-stable": true
}
```

If your Composer credentials already resolve `capell-app/capell`, you can skip this step.

### 3. Install packages

```bash
composer require capell-app/capell -W
php artisan filament:install --panels
php artisan make:filament-theme
```

If you are installing only parts of Capell:

```bash
composer require capell-app/core capell-app/admin capell-app/frontend -W
```

### 4. Prepare your admin user

Capell uses your Laravel `User` model for admin login. Edit `app/Models/User.php` so it implements Filament access and the traits Capell expects:

```php
<?php

declare(strict_types=1);

namespace App\Models;

use BezhanSalleh\FilamentShield\Traits\HasPanelShield;
use Capell\Admin\Models\Concerns\HasImpersonation;
use Filament\Models\Contracts\FilamentUser;
use Filament\Panel;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Spatie\Activitylog\LogOptions;
use Spatie\Activitylog\Traits\LogsActivity;
use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable implements FilamentUser
{
    use HasImpersonation;
    use HasPanelShield;
    use HasRoles;
    use LogsActivity;

    public function canAccessPanel(Panel $panel): bool
    {
        return true;
    }

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
            ->useLogName('user')
            ->logAll()
            ->logExcept(['email_verified_at', 'password', 'remember_token', 'updated_at', 'created_at'])
            ->logOnlyDirty()
            ->dontSubmitEmptyLogs();
    }
}
```

Your real model can keep its existing fillable, hidden, casts, notifications, and factory traits.

### 5. Register Capell in the Filament panel

Edit `app/Providers/Filament/AdminPanelProvider.php` and add the Capell plugin, navigation, colors, and widgets:

```php
<?php

declare(strict_types=1);

namespace App\Providers\Filament;

use Capell\Admin\Enums\FilamentColorEnum;
use Capell\Admin\Facades\CapellAdmin;
use Capell\Admin\Filament\Plugin\CapellAdminPlugin;
use Capell\Admin\Filament\Widgets\ListPagesWidget;
use Capell\Admin\Filament\Widgets\MyWorkQueueWidget;
use Capell\Admin\Filament\Widgets\RecentlyPublishedWidget;
use Capell\Admin\Filament\Widgets\WorkspaceActivityWidget;
use Capell\Admin\Support\AdminPanelEntrypoint;
use Filament\Panel;
use Filament\PanelProvider;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->default()
            ->id('admin')
            ->domain(AdminPanelEntrypoint::domain())
            ->path(AdminPanelEntrypoint::path())
            ->colors(FilamentColorEnum::colors())
            ->navigationItems(CapellAdmin::getNavigationItems())
            ->navigationGroups(CapellAdmin::getNavigationGroups())
            ->plugin(
                CapellAdminPlugin::make()
                    ->discoverSchemas(in: app_path('Filament/FormBuilder'), for: 'App\\Filament\\FormBuilder')
            )
            ->widgets([
                ListPagesWidget::class,
                MyWorkQueueWidget::class,
                RecentlyPublishedWidget::class,
                WorkspaceActivityWidget::class,
            ]);
    }
}
```

`CapellAdminPlugin` auto-registers Capell's required Filament plugins when they
are missing, including the welcome tour plugin. A consuming app does not need a
separate `FilamentTourPlugin::make()` call for the default admin tour.

The helper keeps the panel aligned with `CAPELL_ADMIN_PATH` and
`CAPELL_ADMIN_DOMAIN`. Use it if you want `/cms`, an admin subdomain, or a
subdomain root instead of `/admin`. See [Admin](../admin/index.md).

Install optional login auditing from the dedicated package by running `composer require capell-app/login-audit`, then `php artisan migrate`.

### 6. Configure storage, logging, and queues

Add the static HTML disk to `config/filesystems.php`:

```php
'page_cache' => [
    'driver' => 'local',
    'root' => public_path('page-cache'),
    'throw' => false,
],
```

Add a Capell log channel to `config/logging.php`:

```php
'capell' => [
    'driver' => 'single',
    'path' => storage_path('logs/capell.log'),
    'level' => env('LOG_LEVEL', 'debug'),
],
```

For local development:

```ini
QUEUE_CONNECTION=sync
DEBUG_SKIP_CACHE=true
CAPELL_HTML_CACHE=false
HTML_MINIFY=false
```

For production, use `database` or `redis` queues and run a worker.

### 7. Theme compilation

Add Capell sources to `resources/css/filament/admin/theme.css`:

```css
@source '../../../../vendor/capell-app/admin/resources/views/**/*.blade.php';
@source '../../../../storage/capell/tailwind-classes.txt';
@source '../../../../app/Filament/**/*';
@source '../../../../resources/views/filament/**/*';
```

If you install ContentSections, themes, or other approved packages with Filament views, add their `@source` lines too.

### 8. Run the installer

```bash
php artisan capell:install --url=https://example.test
```

For a demo install:

```bash
php artisan capell:install --demo --url=http://localhost:8000
```

Common installer flags:

| Flag                       | Use it for                                                |
| -------------------------- | --------------------------------------------------------- |
| `--demo`                   | Seed sample pages and content                             |
| `--fresh`                  | Run `migrate:fresh` first. This deletes data              |
| `--url=https://...`        | Skip the site URL prompt                                  |
| `--user=email@example.com` | Attach Capell admin access to an existing user            |
| `--theme=corporate`        | Skip the starter theme prompt                             |
| `--all-packages`           | Install all composer-installed Capell packages            |
| `--generate-sitemap`       | Generate XML sitemaps when a sitemap package is installed |
| `--clear-cache`            | Clear Laravel and page caches after install               |

Interactive installs ask which starter theme to install, including a no-theme option. Use `--theme=none` to install without a starter theme non-interactively, or pass a specific package-provided theme key. For example:

```bash
php artisan capell:install --packages=capell-app/theme-corporate --theme=corporate --url=https://example.test
```

### 9. Verify the install

```bash
php artisan optimize:clear
php artisan list capell
```

If `capell-app/html-cache` is installed, you can also run `php artisan capell:static-site` to warm the public HTML cache. Open the app through Herd, Valet, Sail, or your normal local web server. Then visit `/admin`. You should see the dashboard:

![Capell admin dashboard](../images/admin-dashboard.png)

Then open **Pages** and confirm the page tree loads:

![Capell pages list](../images/admin-pages-list.png)

## Path B: existing Laravel app

Before installing, back up your database and review route ownership. Capell can own the frontend routes, but you may already have application routes that need to stay first.

1. Confirm the app runs on PHP 8.3+ and Laravel 11.44.2+.
2. Add Capell repositories if needed.
3. Install `capell-app/capell` or the three core packages.
4. Update your existing `User` model instead of replacing it.
5. Merge the Capell panel configuration into your existing Filament panel.
6. Add the `page_cache` disk and `capell` log channel.
7. Run `php artisan capell:install --user=admin@example.com --url=https://your-site.test`.
8. Remove Laravel's default welcome route only if Capell should handle `/`.
9. If `capell-app/html-cache` is installed, run `php artisan capell:static-site` and preview a non-critical page first.

If you already have content, read [Multi-site & Multi-lingual](https://docs.capell.app/multi-site-multi-lingual/) before creating sites and languages.

## Optional add-ons

Install only the packages you need:

| Need                         | Package                       | Commands                                                                                      |
| ---------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------- |
| Visual page builder          | `capell-app/content-sections` | `composer require capell-app/content-sections && php artisan capell:content-sections-install` |
| Blog/articles                | `capell-app/blog`             | `composer require capell-app/blog && php artisan capell:blog-install`                         |
| Address fields               | `capell-app/address`          | `composer require capell-app/address && php artisan capell:address-install`                   |
| SEO and AI-assisted metadata | `capell-app/seo-suite`        | `composer require capell-app/seo-suite && php artisan capell:seo-suite-install`               |
| Curator media backend        | `capell-app/media-library`    | `composer require capell-app/media-library`                                                   |

See [approved packages](../packages/catalog.md) for dependencies and tradeoffs.

## Web server setup

For production performance, configure Apache or Nginx to serve `public/page-cache` files before PHP. See [server configuration](https://docs.capell.app/packages/frontend/server-config/) for copy-paste rules.

## Next

- [Quickstart](quickstart.md) for a fast demo path.
- [Quickstart](quickstart.md) for the fastest admin walkthrough.
- [Operations](../operations/index.md) for common first-run failures.
- [Frontend](../frontend/index.md) for caching, Tailwind, translations, and site resolution.