Download the PHP package adityarizqi/laradox without Composer

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

Step 2: Install Laravel Octane

Step 3: Install Laradox

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:

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:

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.

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:

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:

Production:

Step 6: Install Dependencies

Step 7: Setup Laravel

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:

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:

Interactive Shell Access

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

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

Docker Compose Commands

For direct control over Docker:

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:

Configuration File

Publish and customize the configuration file:

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:

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:

2. Generate SSL certificate:

3. Restart the containers to apply the domain change:

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:

Rebuild the containers:

SSL Certificate Issues

Reinstall mkcert and regenerate certificates:

Port Conflicts

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

Then restart the containers:

Containers Already Running

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

Or manually stop and start:

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

Credits

Created by Aditya Rizqi Januarta

Contributing

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