README

Filament One is a powerful and flexible starting point for building robust and scalable admin dashboards. This boilerplate is designed to help developers quickly set up an admin panel with essential features, security measures, and user-friendly management tools.

Built using FilamentPHP, it leverages modern PHP development practices to ensure a smooth and efficient experience.

Key Features:

• User Management: Easily manage user accounts, including registration, profile updates, and deletion.
• Multi-Factor Authentication (MFA): Enhance security with optional two-factor authentication for user accounts.
• API Support: Enable seamless integration with external applications through a robust API layer. Includes authentication, data retrieval, and CRUD operations via RESTful endpoints.
• API Keys Management: Enable secure storage and management of API keys and credentials, facilitating seamless integration with internal and third-party APIs.
• User Roles & Permissions: Implement role-based access control (RBAC) to ensure users have the right level of access.
• Messages: Provides an easy-to-use interface for real-time messaging within Filament admin panels.
• Export Reports: Generate and export reports in Excel (.xlsx) or CSV formats for data analysis and record-keeping.
• Page Builder: A drag-and-drop interface that allows users to create, customize, and manage pages effortlessly. Supports various content blocks, real-time preview, and responsive design to ensure a seamless experience across devices.

Why Choose Filament One?

• Time-Saving: Get started quickly with a ready-to-use admin panel instead of building from scratch.
• Scalability: Designed to be easily extendable, allowing you to add more features as needed.
• Security Focused: Built-in security features like MFA and role-based permissions to protect user data.
• User-Friendly: Clean UI and intuitive navigation for a seamless admin experience.
• Open & Customizable: Modify and extend the boilerplate according to your project’s requirements.

Table of Contents

Setup Local Environment
Setup with Docker
Database
Generate Filament Shield Permissions
Create Administrator Account
Generate Test Data
Initialize The Application
API Support
Troubleshooting
Plugins Used
Acknowledgments
Support

Setup Local Environment

This section covers setting up Filament One for local development without Docker.

Prerequisites

• PHP 8.2 or higher
• Composer
• Node.js 18+ and npm
• MySQL 8.0+ or PostgreSQL 13+
• Redis (optional, for caching and queues)

Step 1: Create Project and Environment File

# Create project
composer create-project jeddsaliba/filament-one
cd filament-one

# Create environment file
cp .env.example .env

Step 2: Generate Application Key

php artisan key:generate

Step 3: Configure Application Settings

Update the following in your .env file:

Application URL:

APP_NAME="Filament One"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost
APP_TIMEZONE=UTC

Step 4: Configure Database

For MySQL:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

For PostgreSQL:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

Important: Make sure you've created the database before running migrations.

Step 5: Configure Redis (Optional but Recommended)

If you have Redis installed locally:

REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null
REDIS_DB=0
REDIS_CACHE_DB=1

# Use Redis for cache and sessions
CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

Step 6: Configure Mailer

Update mail settings in your .env file:

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="noreply@example.com"
MAIL_FROM_NAME="${APP_NAME}"

Note: For local development, you can use Mailpit or MailHog for testing emails.

Step 7: Build Frontend Assets

Install npm dependencies and build assets:

npm install
npm run build

Or for development with hot reload:

npm run dev

Next Steps

After completing the setup above, proceed to:

• Database Migrations
• Generate Filament Shield Permissions
• Create Administrator Account
• Generate Test Data

Setup with Docker

Filament One includes Docker configuration for easy local development. This setup includes PHP-FPM, Nginx, MySQL, Redis, and a queue worker - everything you need to get started quickly.

Prerequisites

• Docker Desktop installed (includes Docker and Docker Compose)
• At least 4GB of available RAM
• Ports 80, 3306, and 6379 available

Docker Services Included

The Docker setup provides the following services:

Step 1: Create Project and Environment File

# Create project
composer create-project jeddsaliba/filament-one
cd filament-one

# Create environment file
cp .env.example .env

Step 2: Configure Docker-Specific Environment Variables

⚠️ Critical: Docker services communicate using service names as hostnames. Your .env file must use these service names.

Update your .env file with the following Docker-specific configuration:

# Application Settings
APP_NAME="Filament One"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost
APP_TIMEZONE=UTC

# Database Configuration
# ⚠️ DB_HOST must be 'mysql' (Docker service name, not localhost!)
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Redis Configuration
# ⚠️ REDIS_HOST must be 'redis' (Docker service name, not localhost!)
REDIS_CLIENT=phpredis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=null
REDIS_DB=0
REDIS_CACHE_DB=1

# Cache & Session (using Redis)
CACHE_STORE=redis
SESSION_DRIVER=redis
SESSION_LIFETIME=120

# Queue Configuration
QUEUE_CONNECTION=redis

# Mail Configuration (optional)
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="noreply@example.com"
MAIL_FROM_NAME="${APP_NAME}"

Important Notes:

• DB_HOST=mysql - Must use the Docker service name, not 127.0.0.1 or localhost
• REDIS_HOST=redis - Must use the Docker service name, not 127.0.0.1 or localhost
• Database credentials (DB_DATABASE, DB_USERNAME, DB_PASSWORD) are used by both Laravel and the MySQL container initialization

Step 3: Build and Start Docker Containers

# Build the containers
docker-compose build

# Start all services in detached mode
docker-compose up -d

All services should show as "Up" or "running".

Step 4: Generate Application Key

docker-compose exec app php artisan key:generate

Next Steps

After completing the Docker setup:

• Database Migrations
• Generate Filament Shield Permissions
• Create Administrator Account
• Generate Test Data

Troubleshooting Docker Setup

If you encounter issues, see the Troubleshooting section below.

Database

Without Docker

Assuming that you have already created an empty database, run this command to migrate the database tables:

php artisan migrate

With Docker

If you're using Docker, the database is automatically created. Just run:

docker-compose exec app php artisan migrate

Generate Filament Shield Permissions

Without Docker

In order to generate filament shield permissions, run this command:

php artisan shield:generate --all

With Docker

docker-compose exec app php artisan shield:generate --all

Create Administrator Account

Without Docker

In order to create an administrator account, run this command:

php artisan shield:super-admin

With Docker

docker-compose exec app php artisan shield:super-admin

Generate Test Data

Without Docker

You may also run this command in order to populate the database with test data:

php artisan db:seed

With Docker

docker-compose exec app php artisan db:seed

Initialize The Application

Without Docker

Option 1: Using Vite (Recommended for development)

npm run dev

In another terminal, start the PHP server:

php artisan serve

Option 2: Build assets for production

npm run build
php artisan serve

With Docker

Start all services:

docker-compose up -d

The application will be available at http://localhost. The Docker setup includes:

• Nginx web server
• PHP-FPM application server
• Queue worker (runs automatically)
• MySQL database
• Redis cache

Note: For frontend development with hot reload, you may want to run Vite separately on your host machine:

npm run dev

Or use the Docker Node service (if configured) for a fully containerized development environment.

API Support

Integrate Filament One with external applications via APIs.
Here is the postman collection. Just import it and you're all set!

Troubleshooting

CSS and JS not working

Without Docker:

npm run build

With Docker:

docker-compose exec app npm run build

Or rebuild the assets in the container:

docker-compose exec app sh -c "npm install && npm run build"

Plugins Used

These are Filament Plugins use for this project.

Acknowledgments

• FilamentPHP
• Laravel

Support

• Report a bug
• Request a feature
• Email support

Show Your Support

Give a ⭐️ if this project helped you!