From 4672d26190c82ae4a35c524138edb93c1114e6ef Mon Sep 17 00:00:00 2001 From: Maxime Helias Date: Sat, 6 Apr 2024 04:53:44 +0200 Subject: [PATCH] docs: add all options available with env var (#598) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: add all options available with env var * Update docs/options.md Co-authored-by: Kévin Dunglas * Update docs/options.md --------- Co-authored-by: Kévin Dunglas --- README.md | 2 +- docs/build.md | 49 ---------------------------------- docs/options.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 72 insertions(+), 50 deletions(-) delete mode 100644 docs/build.md create mode 100644 docs/options.md diff --git a/README.md b/README.md index ab9d571..3f654bb 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ with [FrankenPHP](https://frankenphp.dev) and [Caddy](https://caddyserver.com/) ## Docs -1. [Build options](docs/build.md) +1. [Options available](docs/options.md) 2. [Using Symfony Docker with an existing project](docs/existing-project.md) 3. [Support for extra services](docs/extra-services.md) 4. [Deploying in production](docs/production.md) diff --git a/docs/build.md b/docs/build.md deleted file mode 100644 index 964dab7..0000000 --- a/docs/build.md +++ /dev/null @@ -1,49 +0,0 @@ -# Build Options - -## Selecting a Specific Symfony Version - -Use the `SYMFONY_VERSION` environment variable to select a specific Symfony version. - -For instance, use the following command to install Symfony 6.4: - -On Linux: - - SYMFONY_VERSION=6.4.* docker compose up -d --wait -On Windows: - - set SYMFONY_VERSION=6.4.* && docker compose up -d --wait&set SYMFONY_VERSION= - -## Installing Development Versions of Symfony - -To install a non-stable version of Symfony, use the `STABILITY` environment variable during the build. -The value must be [a valid Composer stability option](https://getcomposer.org/doc/04-schema.md#minimum-stability). - -For instance, use the following command to use the development branch of Symfony: - -On Linux: - - STABILITY=dev docker compose up -d --wait - -On Windows: - - set STABILITY=dev && docker compose up -d --wait&set STABILITY= - -## Customizing the Server Name - -Use the `SERVER_NAME` environment variable to define your custom server name(s). - - SERVER_NAME="app.localhost" docker compose up -d --wait - -> [!TIP] -> You can define your server name variable in your `.env` file to keep it at each up - -## Using custom HTTP ports - -Use the environment variables `HTTP_PORT`, `HTTPS_PORT` and/or `HTTP3_PORT` to adjust the ports to your needs, e.g. - - HTTP_PORT=8000 HTTPS_PORT=4443 HTTP3_PORT=4443 docker compose up -d --wait - -to access your application on [https://localhost:4443](https://localhost:4443). - -> [!NOTE] -> Let's Encrypt only supports the standard HTTP and HTTPS ports. Creating a Let's Encrypt certificate for another port will not work, you have to use the standard ports or to configure Caddy to use another provider. diff --git a/docs/options.md b/docs/options.md new file mode 100644 index 0000000..a6bca26 --- /dev/null +++ b/docs/options.md @@ -0,0 +1,71 @@ +# Docker Build Options + +You can customize the docker build process using these environment variables. + +> [!NOTE] +> All Symfony-specific environment variables are used only if no `composer.json` file is found in the project directory. + +## Selecting a Specific Symfony Version + +Use the `SYMFONY_VERSION` environment variable to select a specific Symfony version. + +For instance, use the following command to install Symfony 6.4: + +On Linux: + + SYMFONY_VERSION=6.4.* docker compose up -d --wait +On Windows: + + set SYMFONY_VERSION=6.4.* && docker compose up -d --wait&set SYMFONY_VERSION= + +## Installing Development Versions of Symfony + +To install a non-stable version of Symfony, use the `STABILITY` environment variable during the build. +The value must be [a valid Composer stability option](https://getcomposer.org/doc/04-schema.md#minimum-stability). + +For instance, use the following command to use the development branch of Symfony: + +On Linux: + + STABILITY=dev docker compose up -d --wait + +On Windows: + + set STABILITY=dev && docker compose up -d --wait&set STABILITY= + +## Using custom HTTP ports + +Use the environment variables `HTTP_PORT`, `HTTPS_PORT` and/or `HTTP3_PORT` to adjust the ports to your needs, e.g. + + HTTP_PORT=8000 HTTPS_PORT=4443 HTTP3_PORT=4443 docker compose up -d --wait + +to access your application on [https://localhost:4443](https://localhost:4443). + +> [!NOTE] +> Let's Encrypt only supports the standard HTTP and HTTPS ports. Creating a Let's Encrypt certificate for another port will not work, you have to use the standard ports or to configure Caddy to use another provider. + + +## Caddyfile Options + +You can also customize the `Caddyfile` by using the following environment variables to inject options block, directive or configuration. + +> [!TIP] +> All the following environment variables can be defined in your `.env` file at the root of the project to keep them persistent at each startup + +| Environment variable | Description | Default value | +|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------| +| `CADDY_GLOBAL_OPTIONS` | the [global options block](https://caddyserver.com/docs/caddyfile/options#global-options), one per line | | +| `CADDY_EXTRA_CONFIG` | the [snippet](https://caddyserver.com/docs/caddyfile/concepts#snippets) or the [named-routes](https://caddyserver.com/docs/caddyfile/concepts#named-routes) options block, one per line | | +| `CADDY_SERVER_EXTRA_DIRECTIVES` | the [`Caddyfile` directives](https://caddyserver.com/docs/caddyfile/concepts#directives) | | +| `SERVER_NAME` | the server name or address | `localhost` | +| `FRANKENPHP_CONFIG` | a list of extra [FrankenPHP directives](https://frankenphp.dev/docs/config/#caddyfile-config), one per line | `import worker.Caddyfile` | +| `MERCURE_TRANSPORT_URL` | the value passed to the `transport_url` directive | `bolt://mercure.db` | +| `MERCURE_PUBLISHER_JWT_KEY` | the JWT key to use for publishers | | +| `MERCURE_PUBLISHER_JWT_ALG` | the JWT algorithm to use for publishers | `HS256` | +| `MERCURE_SUBSCRIBER_JWT_KEY` | the JWT key to use for subscribers | | +| `MERCURE_SUBSCRIBER_JWT_ALG` | the JWT algorithm to use for subscribers | `HS256` | +| `MERCURE_EXTRA_DIRECTIVES` | a list of extra [Mercure directives](https://mercure.rocks/docs/hub/config), one per line | | + +### Example of server name customize: + + SERVER_NAME="app.localhost" docker compose up -d --wait