initial commit

docs/build.md

@@ -0,0 +1,49 @@
+# 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 5.4:
+
+On Linux:
+
+    SYMFONY_VERSION=5.4.* docker compose up --build
+On Windows:
+
+    set SYMFONY_VERSION=5.4.*&& docker compose up --build&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 --build
+On Windows:
+    
+    set STABILITY=dev&& docker compose up --build&set STABILITY=
+  
+
+## Customizing the Server Name
+
+Use the `SERVER_NAME` environment variable to define your custom server name(s).
+
+    SERVER_NAME="app.localhost, caddy:80" docker compose up --build
+
+If you use Mercure, keep `caddy:80` in the list to allow the PHP container to request the caddy service.
+
+*Tips: 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 --build
+
+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.*

docs/existing-project.md

@@ -0,0 +1,33 @@
+# Installing on an Existing Project
+
+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.
+
+Then, copy the Docker-related files from the skeleton to your existing project:
+
+    cp -Rp symfony-docker/. my-existing-project/
+
+Enable the Docker support of Symfony Flex:
+
+    composer config --json extra.symfony.docker 'true'
+
+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
+
+Double-check the changes, revert the changes that you don't want to keep:
+
+    git diff
+    ...
+
+Build the Docker images:
+
+    docker compose build --no-cache --pull
+
+Start the project!
+
+    docker compose up -d
+
+Browse `https://localhost`, your Docker configuration is ready!

docs/extra-services.md

@@ -0,0 +1,12 @@
+# Support for Extra Services
+
+Symfony Docker is extensible. When you install a compatible Composer package using Symfony Flex,
+the recipe will automatically modify the `Dockerfile` and `docker-compose.yml` to fulfill the requirements of this package.
+
+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
+* `blackfireio/blackfire-symfony-meta`: install a Blackfire service

docs/makefile.md

@@ -0,0 +1,90 @@
+# Makefile
+
+Here is a Makefile template. It provides some shortcuts for the most common tasks.
+To use it, create a new `Makefile` file at the root of your project. Copy/paste
+the content in the template section. To view all the available commands, run `make`.
+
+For example, in the [getting started section](/README.md#getting-started), the
+`docker compose` commands could be replaced by:
+
+1. Run `make build` to build fresh images
+2. Run `make up` (detached mode without logs)
+3. Run `make down` to stop the Docker containers
+
+Of course, this template is basic for now. But, as your application is growing,
+you will probably want to add some targets like running your tests as described
+in [the Symfony book](https://symfony.com/doc/current/the-fast-track/en/17-tests.html#automating-your-workflow-with-a-makefile).
+You can also find a more complete example in this [snippet](https://www.strangebuzz.com/en/snippets/the-perfect-makefile-for-symfony).
+
+If you want to run make from within the `php` container, in the [Dockerfile](/Dockerfile),
+add:
+
+```diff
+gettext \
+git \
++make \
+```
+
+And rebuild the PHP image.
+
+**PS**: If using Windows, you have to install [chocolatey.org](https://chocolatey.org/)
+or use [Cygwin](http://cygwin.com) to use the `make` command. Check out this
+[StackOverflow question](https://stackoverflow.com/q/2532234/633864) for more explanations.
+
+## The template
+
+```Makefile
+# Executables (local)
+DOCKER_COMP = docker compose
+
+# Docker containers
+PHP_CONT = $(DOCKER_COMP) exec php
+
+# Executables
+PHP      = $(PHP_CONT) php
+COMPOSER = $(PHP_CONT) composer
+SYMFONY  = $(PHP_CONT) bin/console
+
+# Misc
+.DEFAULT_GOAL = help
+.PHONY        : help build up start down logs sh composer vendor sf cc
+
+## —— 🎵 🐳 The Symfony Docker Makefile 🐳 🎵 ——————————————————————————————————
+help: ## Outputs this help screen
+	@grep -E '(^[a-zA-Z0-9\./_-]+:.*?##.*$$)|(^##)' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}{printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}' | sed -e 's/\[32m##/[33m/'
+
+## —— Docker 🐳 ————————————————————————————————————————————————————————————————
+build: ## Builds the Docker images
+	@$(DOCKER_COMP) build --pull --no-cache
+
+up: ## Start the docker hub in detached mode (no logs)
+	@$(DOCKER_COMP) up --detach
+
+start: build up ## Build and start the containers
+
+down: ## Stop the docker hub
+	@$(DOCKER_COMP) down --remove-orphans
+
+logs: ## Show live logs
+	@$(DOCKER_COMP) logs --tail=0 --follow
+
+sh: ## Connect to the PHP FPM container
+	@$(PHP_CONT) sh
+
+## —— Composer 🧙 ——————————————————————————————————————————————————————————————
+composer: ## Run composer, pass the parameter "c=" to run a given command, example: make composer c='req symfony/orm-pack'
+	@$(eval c ?=)
+	@$(COMPOSER) $(c)
+
+vendor: ## Install vendors according to the current composer.lock file
+vendor: c=install --prefer-dist --no-dev --no-progress --no-scripts --no-interaction
+vendor: composer
+
+## —— Symfony 🎵 ———————————————————————————————————————————————————————————————
+sf: ## List all Symfony commands or pass the parameter "c=" to run a given command, example: make sf c=about
+	@$(eval c ?=)
+	@$(SYMFONY) $(c)
+
+cc: c=c:c ## Clear the cache
+cc: sf
+```

docs/production.md

@@ -0,0 +1,104 @@
+# Deploying in Production
+
+Symfony Docker provides Docker images, and a Docker Compose definition optimized for production usage.
+In this tutorial, we will learn how to deploy our Symfony application on a single server using Docker Compose.
+
+## Preparing a Server
+
+To deploy your application in production, you need a server.
+In this tutorial we will use a virtual machine provided by DigitalOcean, but any Linux server can work.
+If you already have a Linux server with Docker Compose installed, you can skip straight to [the next section](#configuring-a-domain-name).
+
+Otherwise, use [this affiliate link](https://m.do.co/c/5d8aabe3ab80) to get $100 of free credit, create an account, then click on "Create a Droplet".
+Then, click on the "Marketplace" tab under the "Choose an image" section and search for the app named "Docker".
+This will provision an Ubuntu server with the latest versions of Docker and Docker Compose already installed!
+
+To test, the cheapest plan will be enough, but for real production usage you'll probably want to pick a plan in the "general purpose" section that will fit your needs.
+
+![Deploying a Symfony app on DigitalOcean with Docker Compose](digitalocean-droplet.png)
+
+You can keep the defaults for other settings, or tweak them according to your needs.
+Don't forget to add your SSH key or to create a password then press the "Finalize and create" button.
+
+Then, wait a few seconds while your Droplet is provisioning.
+When your Droplet is ready, use SSH to connect:
+
+```console
+ssh root@<droplet-ip>
+```
+
+## Configuring a Domain Name
+
+In most cases, you'll want to associate a domain name to your website.
+If you don't own a domain name yet, you'll have to buy one through a registrar.
+Use [this affiliate link](https://gandi.link/f/93650337) to redeem a 20% discount at Gandi.net.
+
+Then create a DNS record of type `A` for your domain name pointing to the IP address of your server.
+
+Example:
+
+```dns
+your-domain-name.example.com.  IN  A     207.154.233.113
+````
+
+Example in Gandi's UI:
+
+![Creating a DNS record at Gandi.net](gandi-dns.png)
+
+Note: Let's Encrypt, the service used by default by Symfony Docker to automatically generate a TLS certificate doesn't support using bare IP addresses.
+Using a domain name is mandatory to use Let's Encrypt.
+
+## Deploying
+
+Copy your project on the server using `git clone`, `scp` or any other tool that may fit your need.
+If you use GitHub, you may want to use [a deploy key](https://docs.github.com/en/free-pro-team@latest/developers/overview/managing-deploy-keys#deploy-keys).
+Deploy keys are also [supported by GitLab](https://docs.gitlab.com/ee/user/project/deploy_keys/). 
+
+Example with Git:
+
+```console
+git clone git@github.com:<username>/<project-name>.git
+```
+
+Go into the directory containing your project (`<project-name>`), and start the app in production mode:
+
+```console
+SERVER_NAME=your-domain-name.example.com \
+APP_SECRET=ChangeMe \
+CADDY_MERCURE_JWT_SECRET=ChangeThisMercureHubJWTSecretKey \
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+Be sure to replace `your-domain-name.example.com` by your actual domain name and to set the values of `APP_SECRET`, `CADDY_MERCURE_JWT_SECRET` to cryptographically secure random values.
+
+Your server is up and running, and a Let's Encrypt HTTPS certificate has been automatically generated for you.
+Go to `https://your-domain-name.example.com` and enjoy!
+
+## Disabling HTTPS
+
+Alternatively, if you don't want to expose an HTTPS server but only an HTTP one, run the following command:
+
+```console
+SERVER_NAME=:80 \
+APP_SECRET=ChangeMe \
+CADDY_MERCURE_JWT_SECRET=ChangeThisMercureHubJWTSecretKey \
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+## Deploying on Multiple Nodes
+
+If you want to deploy your app on a cluster of machines, you can use [Docker Swarm](https://docs.docker.com/engine/swarm/stack-deploy/),
+which is compatible with the provided Compose files.
+
+## Configuring a Load Balancer or a Reverse Proxy
+
+Since Caddy 2.5, XFF values of incoming requests will be ignored to prevent spoofing.
+So if Caddy is not the first server being connected to by your clients (for example when a CDN is in front of Caddy), you may configure `trusted_proxies` with a list of IP ranges (CIDRs) from which incoming requests are trusted to have sent good values for these headers.
+As a shortcut, `private_ranges` may be configured to trust all private IP ranges.
+
+```diff
+-php_fastcgi unix//var/run/php/php-fpm.sock
++php_fastcgi unix//var/run/php/php-fpm.sock {
++    trusted_proxies private_ranges
++}
+```

docs/tls.md

@@ -0,0 +1,38 @@
+# TLS Certificates
+
+## Trusting the Authority
+
+With a standard installation, the authority used to sign certificates generated in the Caddy container is not trusted by your local machine.
+You must add the authority to the trust store of the host :
+
+```
+# Mac
+$ docker cp $(docker compose ps -q caddy):/data/caddy/pki/authorities/local/root.crt /tmp/root.crt && sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /tmp/root.crt
+# Linux
+$ docker cp $(docker compose ps -q caddy):/data/caddy/pki/authorities/local/root.crt /usr/local/share/ca-certificates/root.crt && sudo update-ca-certificates
+# Windows
+$ docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt %TEMP%/root.crt && certutil -addstore -f "ROOT" %TEMP%/root.crt
+```
+
+## Using Custom TLS Certificates
+
+By default, Caddy will automatically generate TLS certificates using Let's Encrypt or ZeroSSL.
+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: 
+   `mkdir docker/caddy/certs -p`
+3. Generate the certificates for your local host (example: "server-name.localhost"):
+   `mkcert -cert-file docker/caddy/certs/tls.pem -key-file docker/caddy/certs/tls.key "server-name.localhost"`
+4. Add these lines to the `./docker-compose.override.yml` file about `CADDY_EXTRA_CONFIG` environment and volume for the `caddy` service :
+    ```diff
+    caddy:
+    +  environment:
+    +    CADDY_EXTRA_CONFIG: "tls /etc/caddy/certs/tls.pem /etc/caddy/certs/tls.key"
+      volumes:
+    +    - ./docker/caddy/certs:/etc/caddy/certs:ro
+        - ./public:/srv/app/public:ro
+    ```
+5. Restart your `caddy` container

docs/troubleshooting.md

@@ -0,0 +1,14 @@
+# Troubleshooting
+
+## Editing Permissions on Linux
+
+If you work on linux and cannot edit some of the project files right after the first installation, you can run `docker compose run --rm php chown -R $(id -u):$(id -g) .` to set yourself as owner of the project files that were created by the docker container.
+
+## 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.
+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
+
+See more in the [TLS section](tls.md)

docs/xdebug.md

@@ -0,0 +1,58 @@
+# Using Xdebug
+
+The default development image is shipped with [Xdebug](https://xdebug.org/),
+a popular debugger and profiler for PHP.
+
+Because it has a significant performance overhead, the step-by-step debugger is disabled by default.
+It can be enabled by setting the `XDEBUG_MODE` environment variable to `debug`.
+
+On Linux and Mac:
+
+```
+XDEBUG_MODE=debug docker compose up -d
+```
+
+On Windows:
+
+```
+set XDEBUG_MODE=debug&& docker compose up -d&set XDEBUG_MODE=
+```
+
+## Debugging with Xdebug and PHPStorm
+
+First, [create a PHP debug remote server configuration](https://www.jetbrains.com/help/phpstorm/creating-a-php-debug-server-configuration.html):
+
+1. In the `Settings/Preferences` dialog, go to `PHP | Servers`
+2. Create a new server:
+   * Name: `symfony` (or whatever you want to use for the variable `PHP_IDE_CONFIG`)
+   * Host: `localhost` (or the one defined using the `SERVER_NAME` environment variable)
+   * Port: `443`
+   * Debugger: `Xdebug`
+   * Check `Use path mappings`
+   * Absolute path on the server: `/srv/app`
+
+You can now use the debugger!
+
+1. In PHPStorm, open the `Run` menu and click on `Start Listening for PHP Debug Connections`
+2. Add the `XDEBUG_SESSION=PHPSTORM` query parameter to the URL of the page you want to debug, or use [other available triggers](https://xdebug.org/docs/step_debug#activate_debugger)
+
+    Alternatively, you can use [the **Xdebug extension**](https://xdebug.org/docs/step_debug#browser-extensions) for your preferred web browser. 
+
+3. On command line, we might need to tell PHPStorm which [path mapping configuration](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging-cli.html#configure-path-mappings) should be used, set the value of the PHP_IDE_CONFIG environment variable to `serverName=symfony`, where `symfony` is the name of the debug server configured higher.
+
+    Example:
+
+    ```console
+    XDEBUG_SESSION=1 PHP_IDE_CONFIG="serverName=symfony" php bin/console ...
+    ```
+
+## Troubleshooting
+
+Inspect the installation with the following command. The Xdebug version should be displayed.
+
+```console
+$ docker compose exec php php --version
+
+PHP ...
+    with Xdebug v3.x.x ...
+```