From 12fb11eeaddb0ff63fc8e521c296659d54a83542 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Mon, 29 Apr 2024 17:42:18 +0200 Subject: [PATCH] docs: embedding Laravel apps (#753) * docs: embedding Laravel apps * fix * docs: embedding Octane apps * fix * fix * cs * cs * fix md * path explaination * changing the storage path --- docs/embed.md | 9 +++-- docs/laravel.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+), 3 deletions(-) diff --git a/docs/embed.md b/docs/embed.md index a85d847..d274e13 100644 --- a/docs/embed.md +++ b/docs/embed.md @@ -6,6 +6,8 @@ Thanks to this feature, PHP applications can be distributed as standalone binari Learn more about this feature [in the presentation made by Kévin at SymfonyCon 2023](https://dunglas.dev/2023/12/php-and-symfony-apps-as-standalone-binaries/). +For embedding Laravel applications, [read this specific documentation entry](laravel.md#laravel-apps-as-standalone-binaries). + ## Preparing Your App Before creating the self-contained binary be sure that your app is ready for embedding. @@ -29,7 +31,8 @@ cd $TMPDIR/my-prepared-app echo APP_ENV=prod > .env.local echo APP_DEBUG=0 >> .env.local -# Remove the tests +# Remove the tests and other unneeded files to save space +# Alternatively, add these files with the export-ignore attribute in your .gitattributes file rm -Rf tests/ # Install the dependencies @@ -43,7 +46,7 @@ composer dump-env prod The easiest way to create a Linux binary is to use the Docker-based builder we provide. -1. Create a file named `static-build.Dockerfile` in the repository of your prepared app: +1. Create a file named `static-build.Dockerfile` in the repository of your app: ```dockerfile FROM --platform=linux/amd64 dunglas/frankenphp:static-builder @@ -52,7 +55,7 @@ The easiest way to create a Linux binary is to use the Docker-based builder we p WORKDIR /go/src/app/dist/app COPY . . - # Build the static binary, be sure to select only the PHP extensions you want + # Build the static binary WORKDIR /go/src/app/ RUN EMBED=dist/app/ ./build-static.sh ``` diff --git a/docs/laravel.md b/docs/laravel.md index 629f382..07d60a0 100644 --- a/docs/laravel.md +++ b/docs/laravel.md @@ -73,3 +73,108 @@ The `octane:start` command can take the following options: * `--log-level`: Log messages at or above the specified log level Learn more about [Laravel Octane in its official documentation](https://laravel.com/docs/octane). + +## Laravel Apps As Standalone Binaries + +Using [FrankenPHP's application embedding feature](embed.md), it's possible to distribute Laravel +apps as standalone binaries. + +Follow these steps to package your Laravel app as a standalone binary for Linux: + +1. Create a file named `static-build.Dockerfile` in the repository of your app: + + ```dockerfile + FROM --platform=linux/amd64 dunglas/frankenphp:static-builder + + # Copy your app + WORKDIR /go/src/app/dist/app + COPY . . + + # Remove the tests and other unneeded files to save space + # Alternatively, add these files to a .dockerignore file + RUN rm -Rf tests/ + + # Copy .env file + RUN cp .env.example .env + # Change APP_ENV and APP_DEBUG to be production ready + RUN sed -i'' -e 's/^APP_ENV=.*/APP_ENV=production/' -e 's/^APP_DEBUG=.*/APP_DEBUG=false/' .env + + # Make other changes to your .env file if needed + + # Install the dependencies + RUN composer install --ignore-platform-reqs --no-dev -a + + # Build the static binary + WORKDIR /go/src/app/ + RUN EMBED=dist/app/ ./build-static.sh + ``` + + > [!CAUTION] + > + > Some `.dockerignore` files + > will ignore the `vendor/` directory and `.env` files. Be sure to adjust or remove the `.dockerignore` file before the build. + +2. Build: + + ```console + docker build -t static-laravel-app -f static-build.Dockerfile . + ``` + +3. Extract the binary: + + ```console + docker cp $(docker create --name static-laravel-app-tmp static-laravel-app):/go/src/app/dist/frankenphp-linux-x86_64 frankenphp ; docker rm static-laravel-app-tmp + ``` + +4. Populate caches: + + ```console + ./frankenphp php-cli artisan optimize + ``` + +5. Run database migrations (if any): + + ```console + ./frankenphp php-cli artisan migrate + ```` + +6. Generate app's secret key: + + ```console + ./frankenphp php-cli artisan key:generate + ``` + +7. Start the server: + + ```console + ./frankenphp php-server + ``` + +Your app is now ready! + +Learn more about the options available and how to build binaries for other OSes in the [applications embedding](embed.md) +documentation. + +### Changing The Storage Path + +By default, Laravel stores uploaded files, caches, logs, etc. in the application's `storage/` directory. +This is not suitable for embedded applications, as each new version will be extracted into a different temporary directory. + +Set the `LARAVEL_STORAGE_PATH` environment variable (for example, in your `.env` file) or call the `Illuminate\Foundation\Application::useStoragePath()` method to use a directory outside the temporary directory. + +### Running Octane With Standalone Binaries + +It's even possible to package Laravel Octane apps as standalone binaries! + +To do so, [install Octane properly](#laravel-octane) and follow the steps described in [the previous section](#laravel-apps-as-standalone-binaries). + +Then, to start FrankenPHP in worker mode through Octane, run: + +```console +PATH="$PWD:$PATH" ./frankenphp php-cli artisan octane:frankenphp +``` + +> ![CAUTION] +> +> For the command to work, the standalone binary **must** be named `frankenphp` +> because Octane needs a program named `frankenphp` available in the path.