README

Plug-and-play Docker environment for Laravel with FrankenPHP, Nginx, and Octane support

Laradox provides a production-ready Docker environment optimized for Laravel Octane with FrankenPHP. It's designed for both local development and production deployments, with automatic HTTPS support using mkcert.

Features

🚀 Laravel Octane with FrankenPHP for blazing-fast performance
🔒 HTTPS support - optional for development, required for production
🐳 Docker Compose configurations for development and production
⚡ Nginx as reverse proxy with optimized settings
🔧 Queue workers with Supervisor
⏰ Scheduler with Supercronic
📦 Helper scripts for composer, npm, and php commands
🎯 Easy installation via Composer

Performance

Comparison of performance measurements between without and with FrankenPHP under static test conditions:

Without FrankenPHP	With FrankenPHP

Requirements

PHP 8.2 or higher
Laravel 10.x, 11.x, or 12.x
Docker and Docker Compose (auto-detected, installation prompted if missing)
mkcert (auto-detected, installation prompted if missing)

Installation

Step 1: Install via Composer

composer require adityarizqi/laradox --dev

Step 2: Install Laravel Octane

composer require laravel/octane

Step 3: Install Laradox

php artisan laradox:install

This command will:

Publish Docker configuration files
Publish Docker Compose files for development and production
Publish helper scripts (composer, npm, php)
Create necessary directories
Make scripts executable

Step 4: Setup SSL Certificates

For Development (Optional):

Setup SSL certificates for trusted HTTPS:

php artisan laradox:setup-ssl

Laradox will automatically:

Detect if mkcert is installed
Prompt to install mkcert if missing (supports Ubuntu, Debian, Fedora, CentOS, and macOS)
Guide you through the installation process
Generate certificates once mkcert is available

Or manually:

mkcert -install -cert-file ./docker/nginx/ssl/cert.pem -key-file ./docker/nginx/ssl/key.pem "*.docker.localhost" docker.localhost

Development: SSL is optional. You can run with HTTP only (port 80) without any certificates. Laradox will automatically use HTTP-only configuration.

For Production (Required):

SSL certificates are mandatory for production environments. The laradox:up command will refuse to start production containers without valid SSL certificates.

php artisan laradox:setup-ssl
# Or use --force-ssl=false to bypass (not recommended)

Windows Users: mkcert installation is not automated on Windows. Please download from mkcert releases and run manually.

WSL2 Users: Run the mkcert command on the Windows side to install certificates in your Windows trust store.

Step 5: Start Docker Containers

Laradox automatically checks for Docker and Docker Compose before starting containers.

Development:

php artisan laradox:up --detach

If Docker is not installed, Laradox will:

Detect your operating system (Ubuntu, Debian, Fedora, CentOS, macOS, Windows)
Provide installation instructions
Prompt to install Docker automatically (Linux and macOS)
Guide you through the installation process

Or using Docker Compose directly:

docker compose -f docker-compose.development.yml up -d

Production:

php artisan laradox:up --environment=production --detach

Step 6: Install Dependencies

./composer install
./npm install
./npm run dev

Step 7: Setup Laravel

./php artisan key:generate
./php artisan migrate:fresh --seed

You're done! Open https://laravel.docker.localhost to view your application (or http://laravel.docker.localhost if SSL is not configured).

Usage

Artisan Commands

Laradox provides several artisan commands for managing your Docker environment:

# Install Laradox files
php artisan laradox:install [--force]

# Setup SSL certificates
php artisan laradox:setup-ssl [--domain=example.com]

# Start containers (auto-detects SSL)
php artisan laradox:up [--environment=development] [--detach] [--build]

# Force HTTPS (requires SSL certificates)
php artisan laradox:up --force-ssl=true [--detach]

# Force HTTP only (no SSL)
php artisan laradox:up --force-ssl=false [--detach]

# Stop containers
php artisan laradox:down [--environment=development] [--volumes]

# View container logs
php artisan laradox:logs [service] [--follow] [--tail=100] [--timestamps]

# Enter container shell interactively
php artisan laradox:shell [service] [--environment=development] [--user=www-data] [--shell=bash]

SSL Configuration Options

The --force-ssl flag controls SSL behavior:

Not specified (default): Auto-detects SSL certificates
- Development: Prompts if missing, allows HTTP-only
- Production: Requires SSL, fails if missing
--force-ssl=true: Forces HTTPS, requires valid certificates
--force-ssl=false: Forces HTTP-only, ignores certificates

Helper Scripts

The helper scripts allow you to run commands inside containers without entering them:

# Run composer commands
./composer install
./composer update
./composer require vendor/package

# Run npm commands
./npm install
./npm run dev
./npm run build

# Run PHP/Artisan commands
./php artisan migrate
./php artisan queue:work
./php artisan tinker

Interactive Shell Access

Enter containers interactively for debugging, exploration, or manual operations:

# Enter PHP container (default with sh shell)
php artisan laradox:shell

# Enter specific service
php artisan laradox:shell nginx
php artisan laradox:shell node

# Use different shell (automatically falls back to sh if unavailable)
php artisan laradox:shell --shell=bash
php artisan laradox:shell --shell=zsh

# Run as specific user
php artisan laradox:shell --user=www-data

# Production environment
php artisan laradox:shell --environment=production

Available services: php, nginx, node, scheduler, queue

Docker Compose Commands

For direct control over Docker:

# Development
docker compose -f docker-compose.development.yml up -d
docker compose -f docker-compose.development.yml down

# Production
docker compose -f docker-compose.production.yml up -d --build
docker compose -f docker-compose.production.yml down

# View logs
docker compose -f docker-compose.development.yml logs -f

# Restart specific service
docker compose -f docker-compose.development.yml restart php

Configuration

Nginx Configuration

Laradox automatically uses the appropriate nginx configuration based on your environment and SSL availability:

Configuration Files:

app-http.conf - HTTP-only configuration (port 80)
app-https.conf - HTTPS configuration with HTTP→HTTPS redirect
app.conf - Active configuration (auto-generated)

Automatic Selection:

Development with SSL: Uses app-https.conf (HTTPS enabled)
Development without SSL: Prompts user, uses app-http.conf (HTTP-only)
Production: Requires SSL, always uses app-https.conf
--force-ssl=true: Always uses app-https.conf, fails if no certificates
--force-ssl=false: Always uses app-http.conf, ignores certificates

The configuration is automatically selected and copied when you run php artisan laradox:up.

Note: You don't need to manually edit nginx configuration files. Laradox handles this automatically.

Environment Variables

You can customize Laradox behavior using environment variables in your .env file:

# Domain configuration
LARADOX_DOMAIN=laravel.docker.localhost

# Environment
LARADOX_ENV=development

# Ports
LARADOX_HTTP_PORT=80
LARADOX_HTTPS_PORT=443
LARADOX_FRANKENPHP_PORT=8080

# Queue workers (production)
LARADOX_QUEUE_WORKERS=2

# User IDs (for file permissions)
LARADOX_USER_ID=1000
LARADOX_GROUP_ID=1000

Configuration File

Publish and customize the configuration file:

php artisan vendor:publish --tag=laradox-config

Edit config/laradox.php to customize domains, ports, SSL paths, and more.

Services

Laradox includes the following services:

nginx: Reverse proxy with SSL termination
php: FrankenPHP with Laravel Octane
node: Node.js for asset compilation
scheduler: Laravel scheduler (development) or Supercronic (production)
queue: Laravel queue worker with Supervisor (production only)

Scheduler Configuration

The scheduler service handles Laravel's task scheduling differently based on environment:

Development:

Uses php artisan schedule:work for real-time scheduling
Automatically detects and runs scheduled tasks

Production:

Uses Supercronic for reliable cron execution
Configuration file: docker/php/config/schedule.cron
Runs php artisan schedule:run every minute

To modify the schedule in production, edit docker/php/config/schedule.cron:

* * * * * cd /srv && php artisan schedule:run >> /dev/null 2>&1

Note: Define your actual scheduled tasks in app/Console/Kernel.php using Laravel's scheduler. The cron file only triggers Laravel's scheduler.

Customization

Custom Domain

To use a custom domain:

Update the domain in config/laradox.php or .env:
```
LARADOX_DOMAIN=myapp.test
```

Generate SSL certificate:

php artisan laradox:setup-ssl --domain=myapp.test

Restart the containers to apply the domain change:

php artisan laradox:down
php artisan laradox:up --detach

Add domain to your /etc/hosts file (if not using .localhost)

Note: The domain is automatically configured in Nginx using environment variables. You don't need to manually edit docker/nginx/conf.d/app.conf.

Docker Configuration

You can customize the Docker setup by modifying the published files:

docker-compose.development.yml - Development environment
docker-compose.production.yml - Production environment
docker/php/php.dockerfile - PHP/FrankenPHP image
docker/nginx/nginx.conf - Nginx configuration
docker/nginx/conf.d/app.conf - Application server block

Troubleshooting

Permission Issues

If you encounter permission issues, adjust the user IDs:

LARADOX_USER_ID=1000
LARADOX_GROUP_ID=1000

Rebuild the containers:

php artisan laradox:down --volumes
php artisan laradox:up --build --detach

SSL Certificate Issues

Reinstall mkcert and regenerate certificates:

mkcert -uninstall
php artisan laradox:setup-ssl

Port Conflicts

If ports 80/443 are already in use, change them in .env:

LARADOX_HTTP_PORT=8080
LARADOX_HTTPS_PORT=8443

Then restart the containers:

php artisan laradox:down
php artisan laradox:up --detach

Containers Already Running

Laradox automatically detects if containers are already running and offers to restart them:

php artisan laradox:up
# Output: "⚠ Containers are already running!"
# Prompt: "Do you want to restart the containers?"

Or manually stop and start:

php artisan laradox:down
php artisan laradox:up --detach

License

Laradox is open-sourced software licensed under the MIT license.

Testing

Laradox includes a comprehensive test suite covering all functionality. All tests must pass to ensure proper operation.

Running Tests

# Run all tests
composer test

# Run with coverage report
vendor/bin/phpunit --coverage-html build/coverage

# Run specific test suite
vendor/bin/phpunit tests/Feature/
vendor/bin/phpunit tests/Unit/

# Run specific test file
vendor/bin/phpunit tests/Feature/InstallCommandTest.php
vendor/bin/phpunit tests/Unit/UpCommandTest.php

Credits

Created by Aditya Rizqi Januarta

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

adityarizqi / laradox

Maintainers

Details