Provides a PHP generator to produce Dockerfiles and related files. It's target is mostly Laravel, but should work for most PHP applications.
This project provides a CLI application that generates a Dockerfile for your Laravel applications!
The Dockerfile generated by this project aims to provide support for:
- Running your app by default in an Nginx-flavored web server.
- Or, running your app in an Octane-flavored web server: FrankenPHP, RoadRunner, Swoole.
- Building static assets using Vite or Mix
- Running the Scheduler for your background tasks
- Generating Fly.io relevant scripts essential for deploying your application as a Laravel Fly App, if applicable
The Dockerfile generated has been updated to merge with the Dockerfile logic found in https://github.com/fly-apps/laravel-docker, see the Dockerfile ref. This change has been made to allow the use of an upstream image while still providing the base logic provided by the previously used image, fideloper/fly-laravel, which is maintained by that repository. Further, it now visibly provides the necessary configuration files in the user's project directory, specifically in the .fly folder, finally allowing the user full control over these files!
Run composer require fly-apps/dockerfile-laravel --dev in the Laravel project's base directory. After a successful installation, you should now have the binary available at your project's bin directory: vendor/bin/dockerfile-laravel.
Run composer global require fly-apps/dockerfile-laravel. After a successful installation, you should now have the binary available at your composer's, bin directory: <path-to-composer-home>/vendor/bin/dockerfile-laravel. You can view the path to your composer's home directory by checking with composer -n config --global home.
Once dockerfile-laravel has successfully been installed, you can create an alias for it by running: alias dockerfile-laravel='/path-to/vendor/bin/dockerfile-laravel'. Aliasing will allow you to run dockerfile-laravel instead of including the full path to your dockerfile-laravel installation.
If you want to make this package available even outside of your current directory, you can add it to your shell configuration file in your home directory, such as ~/.zshrc or ~/.bashrc, like so:
alias dockerfile-laravel="/path-to/vendor/bin/dockerfile-laravel"
Restart your terminal afterwards, and you should be able to access the dockerfile-laravel globally, thanks to this alias saved in your shell configuration.
Now that you have the dockerfile-laravel installed, you can use it to generate a Dockerfile for your Laravel application. Simply run the generate command of the package:
# Locally run:
vendor/bin/dockerfile-laravel generate
# or, with Alias configured:
dockerfile-laravel generate
And that should generate a Dockerfile at the current directory the command was run in.
-o, --octane[=OCTANE]- If using Octane, provide which flavor - one of: roadrunner, swoole, frankenphp--no-assets- Skip compiling static assets--force- Overwrite existing files--skip- Keep existing files--dev- Include dev dependencies in the creation of the image, i.e. the local .env file--frankenphp-binary- Generate a single file binary of the app via frankenphp
The dockerfile generator accepts the following options:
With your Dockerfile generated, you should now be able to build this Dockerfile into a Docker image:
docker build -t <image-name> .
You can run an instance of this image afterwards:
docker run -p <port-in-your-machine>:8080 <image-name>
And access a containerized instance of your Laravel app in the browser by visiting 127.0.0.1:<port-in-your-machine>!
Feeling a little adventurous, and want to make some experiments with the package? You can do some local development if you want.
Of course, the age-old-question when starting with any new repository: where does one start? First, get familiar with the VIP files of this project:
-
app/Commands/GenerateCommand.php
- This is the entrypoint to the application. This is in charge of generating a Dockerfile in a project's base directory based on the dockerfile.blade.php template, and the flags passed to it.
-
resources/views/dockerfile.blade.php
- This is the template used to generate a Dockerfile
Before diving into making local development changes, there're some to-do's to get you setup with local development on the package:
- Clone the repository
- Get the repo dependencies with
composer install - And, just in case you ever find an error about files not being available, you might be able to fix this with providing the proper permission to the box package used by Laravel Zero framework:
chmod 755 vendor/laravel-zero/framework/bin/box.
Then, yes. After set up, you can make your changes!
Once you've made your changes, you can test them locally by running php dockerfile-laravel generate. This will call the command found in app/Commands/GenerateCommand.php.
Great! You've tested your changes locally. It's time to re-build the stand-alone application for the repository, so that your changes get included in the standalone application that is known as dockerfile-laravel.
Simply run the build command:
php dockerfile-laravel app:build
If changes were made in any of the view files, make sure to clear the cached views( For now, this can be done by manually deleting the cached files ). The path to where the views' caches are stored is configured in config/view.php.
Remember, if you don't delete cached views, your fresh "view changes" are unlikely to be included in the features of the built application.
So, if your view changes don't seem to be working, do delete any cached view files you find, then re-build your changes.
Once you've successfully built your changes, you have to test how it turned out. Simply, in the base of any Laravel project of your choosing run the following:
<path-to-dockerfile-laravel-dir>/builds/dockerfile-laravel generate
And that's it! You should now see a fresh Dockerfile available for your project.
There are two general purpose test cases in tests/Feature/GenerateCommandTest.php:
generates proper templates for each supported base
- Tests that generated files match their references found in the
tests/Feature/Supportedfolder. - Each sub folder in this folder contains:
- Configuration files like
composer.json, or other binaries, used by thegeneratecommand to detect and determine how files are generated - Reference files are files containing the expected contents of files generated from the
generatecommand, i.e., a Dockerfile
- Configuration files like
generates templates with proper snippets
- Tests that specific "snippets" are properly included in specific generated files for special occassions/package support. These snippets expectations are found in
tests/Feature/Snippetsfolder. - Each sub folder in this folder contains:
- Configuration file: their respective
composer.jsonfile. Which, when combined with the composer.json files of base sub folders found intests/Feature/Supportedfolder, should cause specific generated files to contain additional "snippets". Their composer.json file contains an additional custom key:extra.templatesthat lets the test know which specific generated files to test - Reference files: files that match the names found in
extra.templates, and contain the actual snippet expected to be added in that specific template that is generated.
- Configuration file: their respective
- Each sub folder in this folder are combined and tested with all sub folders under
tests/Feature/Supported. This is because their identified snippets are expected to work with all the "base" configurations found in theSupportedsubfolder.
These test cases are used to make sure new changes would not break existing features of the generate command. These can be run through ./vendor/bin/pest.
Once you've cooked up and tested your local changes, you can make a Pull Request to request its inclusion in this repository. ( BONUS points if you add a test case for your change! )
Of course, you don't have to create a PR. If there are any feature or bug that makes sense for the repository, you can also create an Issue about it.
Once submitted, the Laravel team at Fly.io will review your PR/Issue and decide whether it can be successfully added into the official repository. Your contribution will be much appreciated---thank you!