Laradox

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:

1. Update the domain in config/laradox.php or .env:

   LARADOX_DOMAIN=myapp.test

2. Generate SSL certificate:

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

3. Restart the containers to apply the domain change:

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

4. 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.