Merge branch 'main' into update-doc

dunglas · Jun 15, 2024 · c7ce204 · c7ce204
2 parents f37f2b7 + 19dfcbe
commit c7ce204
Show file tree

Hide file tree

Showing 13 changed files with 219 additions and 60 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -40,10 +40,11 @@ jobs:
         run: docker compose up --wait --no-build
       -
         name: Check HTTP reachability
-        run: curl -v -o /dev/null http://localhost
+        run: curl -v --fail-with-body http://localhost
       -
         name: Check HTTPS reachability
-        run: curl -vk -o /dev/null https://localhost
+        if: false # Remove this line when the homepage will be configured, or change the path to check
+        run: curl -vk --fail-with-body https://localhost
       -
         name: Create test database
         if: false # Remove this line if Doctrine ORM is installed

diff --git a/Dockerfile b/Dockerfile
@@ -12,6 +12,8 @@ FROM frankenphp_upstream AS frankenphp_base
 
 WORKDIR /app
 
+VOLUME /app/var/
+
 # persistent / runtime deps
 # hadolint ignore=DL3008
 RUN apt-get update && apt-get install -y --no-install-recommends \

diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@ with [FrankenPHP](https://frankenphp.dev) and [Caddy](https://caddyserver.com/)
 
 1. If not already done, [install Docker Compose](https://docs.docker.com/compose/install/) (v2.10+)
 2. Run `docker compose build --no-cache` to build fresh images
-3. Run `docker compose up --pull always -d --wait` to start the project
+3. Run `docker compose up --pull always -d --wait` to set up and start a fresh Symfony project
 4. Open `https://localhost` in your favorite web browser and [accept the auto-generated TLS certificate](https://stackoverflow.com/a/15076602/1352334)
 5. Run `docker compose down --remove-orphans` to stop the Docker containers.
 
@@ -28,7 +28,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/alpine.md b/docs/alpine.md
@@ -0,0 +1,29 @@
+# Using Alpine Linux Instead of Debian
+
+By default, Symfony Docker uses Debian-based FrankenPHP Docker images.
+This is the recommended solution.
+
+Alternatively, it's possible to use Alpine-based images, which are smaller but
+are known to be slower, and have several known issues.
+
+To switch to Alpine-based images, apply the following changes to the `Dockerfile`:
+
+```patch
+-FROM dunglas/frankenphp:1-php8.3 AS frankenphp_upstream
++FROM dunglas/frankenphp:1-php8.3-alpine AS frankenphp_upstream
+
+-# hadolint ignore=DL3008
+-RUN apt-get update && apt-get install -y --no-install-recommends \
+-	acl \
+-	file \
+-	gettext \
+-	git \
+-	&& rm -rf /var/lib/apt/lists/*
++# hadolint ignore=DL3018
++RUN apk add --no-cache \
++		acl \
++		file \
++		gettext \
++		git \
++	;
+```
diff --git a/docs/build.md b/docs/build.md
diff --git a/docs/existing-project.md b/docs/existing-project.md
@@ -2,9 +2,14 @@
 
 It's also possible to use Symfony Docker with existing projects!
 
-First, [download this skeleton](https://github.com/dunglas/symfony-docker). If you clone the Git repository, be sure to remove the `.git` directory to prevent conflicts with the `.git` directory already in your existing project.
+First, [download this skeleton](https://github.com/dunglas/symfony-docker).
 
-Then, copy the Docker-related files from the skeleton to your existing project:
+If you cloned the Git repository, be sure to not copy the `.git` directory to prevent conflicts with the `.git` directory already in your existing project.
+You can copy the contents of the repository using git and tar. This will not contain `.git` or any uncommited changes.
+
+    git archive --format=tar HEAD | tar -xC my-existing-project/
+
+If you downloaded the skeleton as a zip you can just copy the extracted files:
 
     cp -Rp symfony-docker/. my-existing-project/
 
@@ -15,7 +20,7 @@ Enable the Docker support of Symfony Flex:
 Re-execute the recipes to update the Docker-related files according to the packages you use
 
     rm symfony.lock
-    composer symfony:sync-recipes --force --verbose
+    composer recipes:install --force --verbose
 
 Double-check the changes, revert the changes that you don't want to keep:
 

diff --git a/docs/extra-services.md b/docs/extra-services.md
@@ -8,5 +8,11 @@ The currently supported packages are:
 * `symfony/orm-pack`: install a PostgreSQL service
 * `symfony/mercure-bundle`: use the Mercure.rocks module shipped with Caddy
 * `symfony/panther`: install chromium and these drivers
-* `symfony/mailer`: install a MailCatcher service
+* `symfony/mailer`: install a Mailpit service
 * `blackfireio/blackfire-symfony-meta`: install a Blackfire service
+
+> [!NOTE]
+> If a recipe modifies the Dockerfile, the container needs to be rebuilt.
+
+> [!WARNING]
+> We recommend that you use the `composer require` command inside the container in development mode so that recipes can be applied correctly
diff --git a/docs/makefile.md b/docs/makefile.md
@@ -71,6 +71,9 @@ logs: ## Show live logs
 sh: ## Connect to the FrankenPHP container
 	@$(PHP_CONT) sh
 
+bash: ## Connect to the FrankenPHP container via bash so up and down arrows go to previous commands
+	@$(PHP_CONT) bash
+
 test: ## Start tests with phpunit, pass the parameter "c=" to add options to phpunit, example: make test c="--group e2e --stop-on-failure"
 	@$(eval c ?=)
 	@$(DOCKER_COMP) exec -e APP_ENV=test php bin/phpunit $(c)

diff --git a/docs/mysql.md b/docs/mysql.md
@@ -0,0 +1,72 @@
+# Using MySQL
+
+The Docker configuration of this repository is extensible thanks to Flex recipes. By default, the recipe installs PostgreSQL.
+If you prefer to work with MySQL, follow these steps:
+
+First, install the `symfony/orm-pack` package as described: `docker compose exec php composer req symfony/orm-pack`
+
+## Docker Configuration
+Change the database image to use MySQL instead of PostgreSQL in `compose.yaml`:
+
+```diff
+###> doctrine/doctrine-bundle ###
+-   image: postgres:${POSTGRES_VERSION:-15}-alpine
++   image: mysql:${MYSQL_VERSION:-8}
+    environment:
+-     POSTGRES_DB: ${POSTGRES_DB:-app}
++     MYSQL_DATABASE: ${MYSQL_DATABASE:-app}
+      # You should definitely change the password in production
++     MYSQL_RANDOM_ROOT_PASSWORD: "true"
+-     POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-!ChangeMe!}
++     MYSQL_PASSWORD: ${MYSQL_PASSWORD:-!ChangeMe!}
+-     POSTGRES_USER: ${POSTGRES_USER:-app}
++     MYSQL_USER: ${MYSQL_USER:-app}
+    volumes:
+-     - database_data:/var/lib/postgresql/data:rw
++     - database_data:/var/lib/mysql:rw
+      # You may use a bind-mounted host directory instead, so that it is harder to accidentally remove the volume and lose all your data!
+-     # - ./docker/db/data:/var/lib/postgresql/data:rw
++     # - ./docker/db/data:/var/lib/mysql:rw
+###< doctrine/doctrine-bundle ###
+```
+
+Depending on the database configuration, modify the environment in the same file at `services.php.environment.DATABASE_URL`
+```
+DATABASE_URL: mysql://${MYSQL_USER:-app}:${MYSQL_PASSWORD:-!ChangeMe!}@database:3306/${MYSQL_DATABASE:-app}?serverVersion=${MYSQL_VERSION:-8}&charset=${MYSQL_CHARSET:-utf8mb4}
+```
+
+Since we changed the port, we also have to define this in the `compose.override.yaml`:
+```diff
+###> doctrine/doctrine-bundle ###
+  database:
+    ports:
+-     - "5432"
++     - "3306"
+###< doctrine/doctrine-bundle ###
+```
+
+Last but not least, we need to install the MySQL driver in `Dockerfile`:
+```diff
+###> doctrine/doctrine-bundle ###
+-RUN install-php-extensions pdo_pgsql
++RUN install-php-extensions pdo_mysql
+###< doctrine/doctrine-bundle ###
+```
+
+## Change Environment
+Change the database configuration in `.env`:
+
+```dotenv 
+DATABASE_URL=mysql://${MYSQL_USER:-app}:${MYSQL_PASSWORD:-!ChangeMe!}@database:3306/${MYSQL_DATABASE:-app}?serverVersion=${MYSQL_VERSION:-8}&charset=${MYSQL_CHARSET:-utf8mb4}
+```
+
+## Final steps
+Rebuild the docker environment:
+```shell
+docker compose down --remove-orphans && docker compose build --pull --no-cache
+```
+
+Test your setup:
+```shell
+docker compose exec php bin/console dbal:run-sql -q "SELECT 1" && echo "OK" || echo "Connection is not working"
+```
diff --git a/docs/options.md 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
diff --git a/docs/tls.md b/docs/tls.md
@@ -22,7 +22,7 @@ But sometimes you may prefer using custom certificates.
 For instance, to use self-signed certificates created with [mkcert](https://github.com/FiloSottile/mkcert) do as follows:
 
 1. Locally install `mkcert`
-2. Create the folder storing the certs: 
+2. Create the folder storing the certs:
    `mkdir frankenphp/certs -p`
 3. Generate the certificates for your local host (example: "server-name.localhost"):
    `mkcert -cert-file frankenphp/certs/tls.pem -key-file frankenphp/certs/tls.key "server-name.localhost"`
@@ -37,3 +37,16 @@ For instance, to use self-signed certificates created with [mkcert](https://gith
         - ./public:/app/public:ro
     ```
 5. Restart your `php` service
+
+## Disabling HTTPS for Local Development
+
+To disable HTTPS, configure your environment to use HTTP by setting the following variables and starting the project with this command:
+
+```bash
+SERVER_NAME=http://localhost \
+MERCURE_PUBLIC_URL=http://localhost/.well-known/mercure \
+TRUSTED_HOSTS='^localhost|php$' \
+docker compose up --pull always -d --wait
+```
+
+Ensure your application is accessible over HTTP by visiting `http://localhost` in your web browser.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -6,7 +6,13 @@ If you work on linux and cannot edit some of the project files right after the f
 
 ## HTTPs and Redirects
 
-If Symfony is generating an internal redirect for an `https://` url, but the resulting url is `http://`, you have to uncomment the `TRUSTED_PROXIES` setting in your `.env` file.
+If Symfony is generating an internal redirect for an `https://` url, but the resulting url is `http://`, you have to uncomment the `TRUSTED_PROXIES` setting in your `.env` file and add this line in `config/packages/framework.yaml`:
+```
+# config/packages/framework.yaml
+framework:
+    trusted_proxies: '%env(TRUSTED_PROXIES)%'
+```
+
 For more details see the [Symfony internal redirect documentation](https://symfony.com/doc/current/routing.html#redirecting-to-urls-and-routes-directly-from-a-route).
 
 ## TLS/HTTPS Issues

diff --git a/docs/updating.md b/docs/updating.md
@@ -6,7 +6,7 @@ To import the changes made to the *Symfony Docker* template into your project, w
 1. Run the script to synchronize your project with the latest version of the skeleton:
 
     ```console
-    curl -sSL https://raw.githubusercontent.com/mano-lis/template-sync/main/template-sync.sh | sh -s -- https://github.com/dunglas/symfony-docker
+    curl -sSL https://raw.githubusercontent.com/coopTilleuls/template-sync/main/template-sync.sh | sh -s -- https://github.com/dunglas/symfony-docker
     ```
 
 2. Resolve conflicts, if any