PHPackages adityarizqi/laradox - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [DevOps & Deployment](/categories/devops) 4. / 5. adityarizqi/laradox ActiveLibrary[DevOps & Deployment](/categories/devops) adityarizqi/laradox =================== Plug-and-play Docker environment for Laravel with FrankenPHP, Nginx, and Octane support v2.0.7(3mo ago)897017MITPHPPHP ^8.2CI passing Since Nov 17Pushed 3mo agoCompare [ Source](https://github.com/adityarizqi/laradox)[ Packagist](https://packagist.org/packages/adityarizqi/laradox)[ Docs](https://github.com/adityarizqi/laradox)[ RSS](/packages/adityarizqi-laradox/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (4)Versions (17)Used By (0) Laradox ======= [](#laradox) [![Tests](https://github.com/adityarizqi/laradox/workflows/Tests/badge.svg)](https://github.com/adityarizqi/laradox/actions)[![Latest Stable Version](https://camo.githubusercontent.com/dae29c23a6fe9a9b3c8180af6dedfe911b2e4903ebd58a68c3ce9495bb98fcaf/68747470733a2f2f706f7365722e707567782e6f72672f61646974796172697a71692f6c617261646f782f76)](https://packagist.org/packages/adityarizqi/laradox)[![License](https://camo.githubusercontent.com/06ae78dc34fef6c408cca7f4295b599cf67df311e31067cd52c67c87a3bedda2/68747470733a2f2f706f7365722e707567782e6f72672f61646974796172697a71692f6c617261646f782f6c6963656e7365)](https://packagist.org/packages/adityarizqi/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 -------- [](#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 ----------- [](#performance) Comparison of performance measurements between *without* and *with* FrankenPHP under static test conditions: Without FrankenPHPWith FrankenPHP[![Without FrankenPHP](https://camo.githubusercontent.com/687281d25bf818aa4f135bdedecb9642457c2e4f420b5f356d57c5a71c4a7176/68747470733a2f2f646c2e64726f70626f7875736572636f6e74656e742e636f6d2f73636c2f66692f6c62373271357a7a69367132663662646e7935706e2f776974685f6f75745f6672616e6b656e5f7068702e6a7065673f726c6b65793d766577396f6739676461323575376f66647132766c7365736426653d312673743d64336e6c726e767326646c3d30)](https://camo.githubusercontent.com/687281d25bf818aa4f135bdedecb9642457c2e4f420b5f356d57c5a71c4a7176/68747470733a2f2f646c2e64726f70626f7875736572636f6e74656e742e636f6d2f73636c2f66692f6c62373271357a7a69367132663662646e7935706e2f776974685f6f75745f6672616e6b656e5f7068702e6a7065673f726c6b65793d766577396f6739676461323575376f66647132766c7365736426653d312673743d64336e6c726e767326646c3d30)[![With FrankenPHP](https://camo.githubusercontent.com/38c93191aff9bf11f937c17278f7087c410bf01b2336208710bee9ef27865046/68747470733a2f2f646c2e64726f70626f7875736572636f6e74656e742e636f6d2f73636c2f66692f6962736b6964786668746773783535796b726f6c772f776974685f6672616e6b656e5f7068702e6a7065673f726c6b65793d6a39646e687963756675747472726370746a6d34683738366d26653d312673743d79716f666363683226646c3d30)](https://camo.githubusercontent.com/38c93191aff9bf11f937c17278f7087c410bf01b2336208710bee9ef27865046/68747470733a2f2f646c2e64726f70626f7875736572636f6e74656e742e636f6d2f73636c2f66692f6962736b6964786668746773783535796b726f6c772f776974685f6672616e6b656e5f7068702e6a7065673f726c6b65793d6a39646e687963756675747472726370746a6d34683738366d26653d312673743d79716f666363683226646c3d30)Requirements ------------ [](#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](https://github.com/FiloSottile/mkcert) (auto-detected, installation prompted if missing) Installation ------------ [](#installation) ### Step 1: Install via Composer [](#step-1-install-via-composer) ``` composer require adityarizqi/laradox --dev ``` ### Step 2: Install Laravel Octane [](#step-2-install-laravel-octane) ``` composer require laravel/octane ``` ### Step 3: Install Laradox [](#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 [](#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](https://github.com/FiloSottile/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 [](#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 [](#step-6-install-dependencies) ``` ./composer install ./npm install ./npm run dev ``` ### Step 7: Setup Laravel [](#step-7-setup-laravel) ``` ./php artisan key:generate ./php artisan migrate:fresh --seed ``` You're done! Open to view your application (or if SSL is not configured). Usage ----- [](#usage) ### Artisan Commands [](#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 [](#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 [](#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 [](#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 [](#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 ------------- [](#configuration) ### Nginx 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 [](#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 [](#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 -------- [](#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 [](#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](https://github.com/aptible/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 ------------- [](#customization) ### Custom Domain [](#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 [](#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 --------------- [](#troubleshooting) ### Permission Issues [](#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 [](#ssl-certificate-issues) Reinstall mkcert and regenerate certificates: ``` mkcert -uninstall php artisan laradox:setup-ssl ``` ### Port Conflicts [](#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 [](#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 ------- [](#license) Laradox is open-sourced software licensed under the [MIT license](LICENSE). Testing ------- [](#testing) Laradox includes a comprehensive test suite covering all functionality. All tests must pass to ensure proper operation. ### Running Tests [](#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 ------- [](#credits) Created by [Aditya Rizqi Januarta](https://github.com/adityarizqi) Contributing ------------ [](#contributing) Contributions are welcome! Please feel free to submit a Pull Request. ### Health Score 47 — FairBetter than 94% of packages Maintenance80 Actively maintained with recent releases Popularity27 Limited adoption so far Community14 Small or concentrated contributor base Maturity56 Maturing project, gaining track record Bus Factor1 Top contributor holds 97.8% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~9 days Recently: every ~16 days Total 8 Last Release 107d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/5c37876dc44b1bd40271360d0c0dfd60331780073389f966d8f1223a5ade948f?d=identicon)[adityarizqi](/maintainers/adityarizqi) --- Top Contributors [![adityarizqi](https://avatars.githubusercontent.com/u/64444809?v=4)](https://github.com/adityarizqi "adityarizqi (134 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (2 commits)")[![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?v=4)](https://github.com/coderabbitai[bot] "coderabbitai[bot] (1 commits)") --- Tags phplaraveldockeroctanefrankenphpnginxlaravel-dockerdocker-composelaravel-octanedevelopment-environmentlaradox ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/adityarizqi-laradox/health.svg) ``` [![Health](https://phpackages.com/badges/adityarizqi-laradox/health.svg)](https://phpackages.com/packages/adityarizqi-laradox) ``` ### Alternatives [ryoluo/sail-ssl Laravel Sail plugin to enable SSL (HTTPS) connection with Nginx. 188672.6k2](/packages/ryoluo-sail-ssl)[vcian/pulse-docker-monitor A Laravel Pulse card to show docker containers with CPU & Memory Utilization 348.0k](/packages/vcian-pulse-docker-monitor)[downtoworld/laravel-devops Laravel Cloudflare-Tunnels Ready Production Docker-Compose 161.1k](/packages/downtoworld-laravel-devops) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)