Installation Guide

Because TallCMS is built on Filament, you get access to two plugin ecosystems: TallCMS plugins for CMS features (blocks, themes, frontend routes) and hundreds of Filament community plugins for admin panel enhancements (form fields, data tools, auth providers, and more). Any Filament plugin works with TallCMS out of the box.

System Requirements

Required PHP Extensions

• OpenSSL
• PDO (with MySQL/SQLite driver)
• Mbstring
• Tokenizer
• XML
• Ctype
• JSON
• BCMath
• Fileinfo
• GD or Imagick

Plugin Installation

Add CMS features to your existing Laravel/Filament application.

Step 1: Install the Package

composer require tallcms/cms

This will install TallCMS and its dependencies. If Filament is not already installed, it will be pulled in automatically.

Step 2: Set Up Filament Panel

If you don't have a Filament panel yet:

php artisan filament:install --panels

Step 3: Configure User Model

Your User model must use the HasRoles trait from Spatie Permission:

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasFactory, HasRoles, Notifiable;

    // ...
}

Step 4: Register the Plugin

Add TallCmsPlugin to your panel provider (e.g., app/Providers/Filament/AdminPanelProvider.php):

<?php

namespace App\Providers\Filament;

use Filament\Panel;
use Filament\PanelProvider;
use TallCms\Cms\TallCmsPlugin;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->default()
            ->id('admin')
            ->path('admin')
            // ... other configuration
            ->plugin(TallCmsPlugin::make());
    }
}

Step 5: Run the Installer

php artisan tallcms:install

This command will:

• Check prerequisites (HasRoles trait, panel provider, etc.)
• Publish and run migrations
• Set up roles and permissions
• Activate the TallDaisy theme (styled frontend out of the box)
• Create your admin user interactively

Step 6: Build Frontend Assets

Filament admin pages reference your host app's Vite manifest. Without a built manifest, every admin page returns a 500 (Illuminate\Foundation\ViteManifestNotFoundException).

npm install
npm run build

Or npm run dev during development for hot reload.

Note on block previews: TallCMS ships a pre-built tallcms-preview.css automatically registered through Filament's asset system, so the daisyUI block previews in the page editor work out of the box without touching your vite.config.js. If you want to customise the block-preview styles (e.g. for plugin blocks you've authored), copy vendor/tallcms/cms/resources/css/preview.css into your host app, add it to your vite.config.js input array, and rebuild — the host build wins over the package's pre-built copy when both are present.

At this point the admin panel is functional. Visit /admin, log in, and you can already create Pages and Posts. The next steps wire up the frontend so visitors can see them.

Step 7: Publish TallCMS Frontend Assets

For frontend page styling, publish the TallCMS assets:

php artisan vendor:publish --tag=tallcms-assets

This writes CSS/JS to public/vendor/tallcms/. The frontend loads them automatically once published.

Step 8: Enable Frontend Routes

Frontend routes are disabled by default in plugin mode so TallCMS doesn't override your existing routes. To serve CMS pages on the frontend, add this to your .env:

TALLCMS_ROUTES_ENABLED=true

This registers two routes:

• / — homepage (whichever Page you mark as Homepage in the admin)
• /{slug} — CMS pages by slug

Common app paths (/admin, /api, /livewire, /storage, etc.) are automatically excluded from CMS routing.

Resolve the homepage conflict

A fresh Laravel app ships with Route::get('/', fn () => view('welcome')) in routes/web.php. Laravel loads routes/web.php after package routes, so this default route wins over TallCMS's /. Pick one:

Option A — Remove the welcome route (recommended if you want CMS pages at /):

// In routes/web.php — remove or comment out:
// Route::get('/', function () {
//     return view('welcome');
// });

Option B — Prefix the CMS routes (keeps your welcome page at /):

TALLCMS_ROUTES_PREFIX=cms

CMS pages are then served at /cms (homepage) and /cms/{slug}.

Alpine.js requirement: TallCMS frontend pages need Alpine.js. Most Laravel apps already include it via Livewire. If you load Alpine separately, ensure it loads before tallcms.js — components use alpine:init.

Step 9: Set Your Homepage

In the admin panel, edit any Page and toggle Set as Homepage. That page becomes the default at / (or /cms if you set a route prefix). Until you mark a homepage, / will 404.

Theme Configuration

The installer automatically activates the TallDaisy theme, which provides daisyUI-powered styling for all frontend pages. If your frontend pages appear unstyled after installation:

1. Verify TALLCMS_THEMES_ENABLED is not set to false in your .env
2. Check that public/themes/talldaisy/ exists (run php artisan theme:list)
3. Re-run php artisan tallcms:install --force to re-activate the theme

You can customize the active theme in the admin panel under Appearance > Themes.

Selective Features

Disable components you don't need:

->plugin(
    TallCmsPlugin::make()
        ->withoutPosts()           // Disable blog posts
        ->withoutCategories()      // Disable categories
        ->withoutContactSubmissions()  // Disable contact form submissions
)

Standalone Installation

The standalone installation gives you a complete CMS with themes, plugins, web installer, and auto-updates.

# Create new project
composer create-project tallcms/tallcms my-site

# Navigate to project
cd my-site

# Install frontend dependencies and build assets
npm install && npm run build

# Start development server
php artisan serve

Visit http://localhost:8000/install to complete the web installer. After setup, your admin panel is at http://localhost:8000/admin.

Web Installer

The web installer guides you through:

1. System Check — Verifies PHP version, extensions, and permissions
2. Database Setup — Configure MySQL, MariaDB, or SQLite connection
3. Admin Account — Create your administrator user
4. Site Settings — Set site name, contact email, timezone
5. Mail Configuration — SMTP, Amazon SES, or PHP Mail
6. Cloud Storage (Optional) — S3-compatible storage setup

Manual Configuration (Alternative)

If you prefer command-line setup instead of the web installer:

# Copy environment file
cp .env.example .env

# Generate application key
php artisan key:generate

# Configure your .env file with database credentials
# Then run migrations
php artisan migrate --force

# Create storage symlink
php artisan storage:link

# Create admin user interactively
php artisan make:user

Post-Installation

After installation, access the admin panel at:

https://yourdomain.com/admin

Log in with the admin credentials you created during setup. From here you can:

1. Create pages and posts in Content > Pages and Content > Posts
2. Set up navigation menus in Content > Menus
3. Configure site settings in Settings > Site Settings
4. Customize your theme in Appearance > Themes
5. Manage roles and permissions in Settings > Shield

Tip: The default admin path is /admin. If you changed the panel path during setup, use that instead.

REST API (Plugin Mode)

TallCMS includes a full REST API for headless CMS usage. The API is disabled by default.

Enable the API

Add to your .env file:

TALLCMS_API_ENABLED=true

This registers all API endpoints at /api/v1/tallcms/*.

API Configuration

Webhooks Configuration

Generate API Documentation

Scribe generates interactive API documentation. It's a dev dependency — the /api/docs route only works when Scribe is installed.

composer require --dev knuckleswtf/scribe
php artisan vendor:publish --tag=tallcms-scribe-config
php artisan scribe:generate

The published config sets the docs URL to /api/docs and filters to TallCMS API routes only. Regenerate after modifying API endpoints.

Note: If you already use Scribe for other APIs, the publish command will overwrite your existing config/scribe.php. Merge the TallCMS route prefix into your existing config's routes array instead.

Production: The API endpoints work without Scribe, but /api/docs won't be available. Options:

• Import storage/app/private/scribe/openapi.yaml into Swagger UI or Postman
• Deploy generated docs (resources/views/scribe/) to a separate static host
• Run a staging environment with Scribe installed for documentation

Next Steps

See REST API Development for authentication, endpoints, and usage details.

Cloud Storage Setup

TallCMS supports S3-compatible cloud storage for media uploads.

Supported Providers

• Amazon S3
• DigitalOcean Spaces
• Cloudflare R2
• Backblaze B2
• Wasabi
• MinIO (self-hosted)
• Any S3-compatible provider

Configuration

Option A — use S3 as the default filesystem (simplest):

# Storage credentials
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket-name

# Enable S3 storage
FILESYSTEM_DISK=s3

# For non-AWS providers, add endpoint:
AWS_ENDPOINT=https://nyc3.digitaloceanspaces.com

TallCMS detects FILESYSTEM_DISK=s3 and routes all media uploads to S3 automatically.

Option B — dedicated media disk (when your app's default filesystem stays local):

Define a named disk in config/filesystems.php:

'cms-media' => [
    'driver'     => 's3',
    'key'        => env('CMS_MEDIA_KEY'),
    'secret'     => env('CMS_MEDIA_SECRET'),
    'region'     => env('CMS_MEDIA_REGION', 'us-east-1'),
    'bucket'     => env('CMS_MEDIA_BUCKET'),
    'url'        => env('CMS_MEDIA_URL'),      // optional CDN URL
    'visibility' => 'public',
],

Then tell TallCMS to use it:

TALLCMS_MEDIA_DISK=cms-media

TALLCMS_MEDIA_DISK takes priority over the auto-detection. It accepts any disk name registered in config/filesystems.php.

Provider Examples

DigitalOcean Spaces:

AWS_ACCESS_KEY_ID=your-spaces-key
AWS_SECRET_ACCESS_KEY=your-spaces-secret
AWS_DEFAULT_REGION=nyc3
AWS_BUCKET=my-space-name
AWS_ENDPOINT=https://nyc3.digitaloceanspaces.com
FILESYSTEM_DISK=s3

Cloudflare R2:

AWS_ACCESS_KEY_ID=your-r2-access-key
AWS_SECRET_ACCESS_KEY=your-r2-secret-key
AWS_DEFAULT_REGION=auto
AWS_BUCKET=my-bucket
AWS_ENDPOINT=https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com
FILESYSTEM_DISK=s3

MinIO (Self-Hosted):

AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=my-bucket
AWS_ENDPOINT=http://localhost:9000
AWS_USE_PATH_STYLE_ENDPOINT=true
FILESYSTEM_DISK=s3

Bucket Configuration

Ensure your bucket:

• Allows public read access for uploaded files
• Has CORS configured for direct uploads (if needed)

Mail Configuration

SMTP

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="${APP_NAME}"

Amazon SES

MAIL_MAILER=ses
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="${APP_NAME}"

# Uses same AWS credentials as S3
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1

Note: Amazon SES starts in sandbox mode. You must verify your domain/email and request production access.

Web Server Configuration

Apache

Ensure mod_rewrite is enabled and the .htaccess file in public/ is being processed:

<VirtualHost *:80>
    ServerName yourdomain.com
    DocumentRoot /var/www/tallcms/public

    <Directory /var/www/tallcms/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Nginx

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/tallcms/public;

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

File Permissions

# Set ownership (adjust user/group as needed)
sudo chown -R www-data:www-data /var/www/tallcms

# Set directory permissions
sudo find /var/www/tallcms -type d -exec chmod 755 {} \;

# Set file permissions
sudo find /var/www/tallcms -type f -exec chmod 644 {} \;

# Make storage and cache writable
sudo chmod -R 775 /var/www/tallcms/storage
sudo chmod -R 775 /var/www/tallcms/bootstrap/cache

Upgrading

Standalone Mode

Use the built-in update system in Settings > System Updates, or via CLI:

# Check for updates (dry run)
php artisan tallcms:update --dry-run

# Update to latest version
php artisan tallcms:update

# Update to specific version
php artisan tallcms:update --target=4.0.3

After updating, always run migrations in case the update includes database changes:

php artisan migrate

Plugin Mode

Update via Composer:

composer update tallcms/cms
php artisan migrate
php artisan view:clear

Alternative Installation Methods

These methods are available for standalone installations but are not the recommended approach.

Manual Download

1. Download the latest release from tallcms.com or GitHub Releases
2. Extract the archive to your web server directory
3. Set your web server's document root to the public/ directory
4. Run composer install && npm install && npm run build
5. Visit your domain in a browser and follow the setup wizard

Git Clone (For Contributors)

# Clone the repository
git clone https://github.com/tallcms/tallcms.git
cd tallcms

# Install PHP dependencies
composer install

# Install frontend dependencies and build assets
npm install && npm run build

# Start development server with hot reload
composer dev

Visit http://localhost:8000/install to complete setup. After installation, the admin panel is at http://localhost:8000/admin.

Common Pitfalls

"Installation already complete"Delete storage/installer.lock from project root, or set INSTALLER_ENABLED=true in .env.

"Database connection failed"Verify database credentials in installer form. Ensure database server is running and the database exists.

"Permission denied" during installationEnsure storage/ and bootstrap/cache/ are writable. Run chmod -R 775 storage bootstrap/cache.

"Cannot access admin panel"The admin panel is at /admin (e.g., https://yourdomain.com/admin). Complete the web installer first if you haven't already. Verify your user has an active role. If you changed the panel path in AdminPanelProvider.php, use that path instead.

"403 Forbidden"Clear permission cache: php artisan permission:cache-reset. Verify user has appropriate role.

"CMS resources not appearing"Ensure TallCmsPlugin::make() is registered in your panel provider. Run php artisan migrate to create the CMS tables. Clear config cache: php artisan config:clear.

"Vite manifest not found at: .../public/build/manifest.json" (500 on every admin page)Your host app's frontend assets haven't been built. Run npm install && npm run build from the project root. This is required after a fresh tallcms:install and after any time the public/build/ directory gets cleared.

"Unable to locate file in Vite manifest: resources/css/filament/admin/preview.css" (500 in the page editor)This was a regression in earlier TallCMS releases when running in plugin mode — the rich editor view tried to load a CSS entry only present in standalone's vite.config.js. As of v4.2 the package ships tallcms-preview.css pre-built and registered through Filament's asset system, so the daisyUI block-preview styles load automatically without touching your vite.config.js. Update with composer update tallcms/cms if you're seeing this on an older version.

Next Steps

• Create your first page
• Publish your first post
• Set up navigation menus