docs: refactor and add a doc explaining how to deploy in prod

.gitattributes

@@ -14,5 +14,3 @@ bin/console text eol=lf
 
 *.ico binary
 *.png binary
-
-README.md export-ignore

README.md

@@ -6,9 +6,9 @@ A [Docker](https://www.docker.com/)-based installer and runtime for the [Symfony
 
 ## Getting Started
 
-1. Run `docker-compose up` (the logs will be displayed in the current shell)
+1. If not already done, [install Docker Compose](https://docs.docker.com/compose/install/)
-2. Open `https://localhost` in your favorite web browser and [accept the auto-generated TLS certificate](https://stackoverflow.com/a/15076602/1352334)
+2. Run `docker-compose up` (the logs will be displayed in the current shell)
-3. **Enjoy!**
+3. Open `https://localhost` in your favorite web browser and [accept the auto-generated TLS certificate](https://stackoverflow.com/a/15076602/1352334)
 
 ## Features
 
@@ -19,101 +19,15 @@ A [Docker](https://www.docker.com/)-based installer and runtime for the [Symfony
 * Just 2 services (PHP FPM and Caddy server)
 * Super-readable configuration
 
-## Selecting a Specific Symfony Version
+**Enjoy!**
 
-Use the `SYMFONY_VERSION` environment variable to select a specific Symfony version.
+## Docs
 
-For instance, use the following command to install Symfony 4.4:
+1. [Build options](docs/build.md)
-
+2. [Support for extra services](docs/extra-services.md)
-    $ SYMFONY_VERSION=4.4.* docker-compose up --build
+3. [Deploying in production](docs/production.md)
-
+4. [Installing Xdebug](docs/xdebug.md)
-To install a non-stable version of Symfony, use the `STABILITY` environment variable during the build.
+5. [Troubleshooting](docs/troubleshooting.md)
-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 `master` branch of Symfony:
-
-    $ STABILITY=dev docker-compose up --build
-
-## Customize Server Name
-
-Use the `SERVER_NAME` environment variable to define your custom server name.
-
-    $ SERVER_NAME=symfony.wip docker-compose up --build
-
-## Debugging
-
-The default Docker stack is shipped without a Xdebug stage.
-It's easy though to add [Xdebug](https://xdebug.org/) to your project, for development purposes such as debugging tests or API requests remotely.
-
-### Add a Development Stage to the Dockerfile
-
-To avoid deploying Symfony Docker to production with an active Xdebug extension,
-it's recommended to add a custom stage to the end of the `Dockerfile`.
-
-```Dockerfile
-# Dockerfile
-FROM symfony_php as symfony_php_dev
-
-ARG XDEBUG_VERSION=2.9.8
-RUN set -eux; \
-	apk add --no-cache --virtual .build-deps $PHPIZE_DEPS; \
-	pecl install xdebug-$XDEBUG_VERSION; \
-	docker-php-ext-enable xdebug; \
-	apk del .build-deps
-```
-
-### Configure Xdebug with Docker Compose Override
-
-Using an [override](https://docs.docker.com/compose/reference/overview/#specifying-multiple-compose-files) file named `docker-compose.debug.yaml` ensures that the production
-configuration remains untouched.
-
-As example, an override could look like this:
-
-```yaml
-# docker-compose.debug.yaml
-version: "3.4"
-
-services:
-  php:
-    build:
-      context: .
-      target: symfony_php_dev
-    environment:
-      # See https://docs.docker.com/docker-for-mac/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host
-      # See https://github.com/docker/for-linux/issues/264
-      # The `remote_host` below may optionally be replaced with `remote_connect_back`
-      XDEBUG_CONFIG: >-
-        remote_enable=1
-        remote_host=host.docker.internal
-        remote_port=9001
-        idekey=PHPSTORM
-      # This should correspond to the server declared in PHPStorm `Preferences | Languages & Frameworks | PHP | Servers`
-      # Then PHPStorm will use the corresponding path mappings
-      PHP_IDE_CONFIG: serverName=symfony
-```
-
-Then run:
-
-    $ docker-compose -f docker-compose.yml -f docker-compose.debug.yml up -d
-
-### Troubleshooting
-
-Inspect the installation with the following command. The requested Xdebug version should be displayed in the output.
-
-    $ docker-compose exec php php --version
-    
-    PHP ...
-        with Xdebug v2.8.0 ...
-
-### 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.
-
-### Fix Chrome/Brave SSL
-
-If you have a SSL trust issues, download the self-signed certificate and run :
-
-    $ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/you/certificate.cer
 
 ## Credits
 

docs/build.md

@@ -0,0 +1,22 @@
+# 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 4.4:
+
+    $ SYMFONY_VERSION=4.4.* docker-compose up --build
+
+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 `master` branch of Symfony:
+
+    $ STABILITY=dev docker-compose up --build
+
+## Customizing the Server Name
+
+Use the `SERVER_NAME` environment variable to define your custom server name.
+
+    $ SERVER_NAME=symfony.wip docker-compose up --build

docs/extra-services.md

@@ -0,0 +1,9 @@
+# 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 MariaDB service
+* `symfony/messenger`: install a RabbitMQ service

docs/production.md

@@ -0,0 +1,75 @@
+# 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:
+
+    $ 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:
+
+    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 if 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:
+
+    $ 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:
+
+    $ SERVER_NAME=your-domain-name.example.com 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.
+
+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:
+
+    $ SERVER_NAME=:80 -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.

docs/troubleshooting.md

@@ -0,0 +1,11 @@
+# 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.
+
+## Fix Chrome/Brave SSL
+
+If you have a SSL trust issues, download the self-signed certificate and run :
+
+    $ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/you/certificate.cer

docs/xdebug.md

@@ -0,0 +1,64 @@
+# Installing Xdebug
+
+The default Docker stack is shipped without a Xdebug stage.
+It's easy though to add [Xdebug](https://xdebug.org/) to your project, for development purposes such as debugging tests or API requests remotely.
+
+## Add a Debug Stage to the Dockerfile
+
+To avoid deploying Symfony Docker to production with an active Xdebug extension,
+it's recommended to add a custom stage to the end of the `Dockerfile`.
+
+```Dockerfile
+# Dockerfile
+FROM symfony_php as symfony_php_debug
+
+ARG XDEBUG_VERSION=2.9.8
+RUN set -eux; \
+	apk add --no-cache --virtual .build-deps $PHPIZE_DEPS; \
+	pecl install xdebug-$XDEBUG_VERSION; \
+	docker-php-ext-enable xdebug; \
+	apk del .build-deps
+```
+
+## Configure Xdebug with Docker Compose Override
+
+Using an [override](https://docs.docker.com/compose/reference/overview/#specifying-multiple-compose-files) file named `docker-compose.debug.yaml` ensures that the production
+configuration remains untouched.
+
+As example, an override could look like this:
+
+```yaml
+# docker-compose.debug.yaml
+version: "3.4"
+
+services:
+  php:
+    build:
+      context: .
+      target: symfony_php_debug
+    environment:
+      # See https://docs.docker.com/docker-for-mac/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host
+      # See https://github.com/docker/for-linux/issues/264
+      # The `remote_host` below may optionally be replaced with `remote_connect_back`
+      XDEBUG_CONFIG: >-
+        remote_enable=1
+        remote_host=host.docker.internal
+        remote_port=9001
+        idekey=PHPSTORM
+      # This should correspond to the server declared in PHPStorm `Preferences | Languages & Frameworks | PHP | Servers`
+      # Then PHPStorm will use the corresponding path mappings
+      PHP_IDE_CONFIG: serverName=symfony
+```
+
+Then run:
+
+    $ docker-compose -f docker-compose.yml -f docker-compose.debug.yml up -d
+
+## Troubleshooting
+
+Inspect the installation with the following command. The requested Xdebug version should be displayed in the output.
+
+    $ docker-compose exec php php --version
+    
+    PHP ...
+        with Xdebug v2.8.0 ...