doc: add information about building production image (#752)

* Add information about building production image

* add informations about deploying in production

* Fix typo

* Remove logs

* Maintain common command format

Co-authored-by: Stanislau Kviatkouski <7-zete-7@users.noreply.github.com>

* Add link about how Docker Compose config file merge works

Co-authored-by: Stanislau Kviatkouski <7-zete-7@users.noreply.github.com>

* Maintain common command format

Co-authored-by: Stanislau Kviatkouski <7-zete-7@users.noreply.github.com>

* Maintain common command format

Co-authored-by: Maxime Helias <maximehelias16@gmail.com>

* Fix to build command

Co-authored-by: Stanislau Kviatkouski <7-zete-7@users.noreply.github.com>

---------

Co-authored-by: Stanislau Kviatkouski <7-zete-7@users.noreply.github.com>
Co-authored-by: Maxime Helias <maximehelias16@gmail.com>

Author: 3 people

docs/production.md

@@ -60,6 +60,10 @@ 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
+# Build fresh production image
+docker compose -f compose.yaml -f compose.prod.yaml build --no-cache
+
+# Start container
 SERVER_NAME=your-domain-name.example.com \
 APP_SECRET=ChangeMe \
 CADDY_MERCURE_JWT_SECRET=ChangeThisMercureHubJWTSecretKey \

docs/troubleshooting.md

@@ -7,3 +7,67 @@ If you work on linux and cannot edit some of the project files right after the f
 ## TLS/HTTPS Issues
 
 See more in the [TLS section](tls.md)
+
+## Production issues
+
+### How to properly build fresh images for production use
+
+Remember that, by default, if you run `docker compose up -d`, only the files `compose.yaml` and `compose.override.yaml` will be used.
+See https://docs.docker.com/compose/intro/compose-application-model and https://docs.docker.com/compose/how-tos/multiple-compose-files/merge.
+
+If you need to build images for production environment, you have to use the following command:
+
+```console
+docker compose -f compose.yaml -f compose.prod.yaml build --no-cache
+```
+
+### Why application outputs `phpinfo()`
+
+Both dev and prod images have the same image tag (`<...>app-php:latest`). This can cause confusion when working with images.
+It is important to make sure that your image is the appropriate one for the current environment.
+
+If you are not careful about this, and try to run your production container(s) with
+`docker compose -f compose.yaml -f compose.prod.yaml up -d`
+without the right build process beforehand, your application **will still launch**, but will be displaying an output of `phpinfo()` (or possibly even a HTTP 500 error page).
+
+See details below.
+
+<details>
+
+<summary>Output of a basic build process</summary>
+
+In the case of a dev image, you need the `compose.yaml` and `compose.override.yaml` files. Which are the default files for Docker Compose.
+This means that running `docker compose <command>` or `docker compose -f compose.yaml -f compose.override.yaml <command>` is the same thing.
+
+And in doing so, images `frankenphp_base` and `frankenphp_dev` are built. And not `frankenphp_prod`.
+Which is good enough for dev purposes.
+
+Then, you can start your dev container(s) by running:
+
+```console
+docker compose up -d
+```
+
+
+</details>
+
+<br>
+
+<details>
+
+<summary>Output expected for the production build process</summary>
+
+To build the production image, you <ins>have to</ins> specify the `compose.yaml` and `compose.prod.yaml` files.
+This means you have to run: `docker compose -f compose.yaml -f compose.prod.yaml build` in order to build your image
+(careful: the order of `-f` arguments is important).
+
+That way, you will see that `frankenphp_base` and `frankenphp_prod` are built this time, which is what you will need for production purposes.
+
+You can finally start your prod container(s) by running:
+
+```console
+docker compose -f compose.yaml -f compose.prod.yaml up -d
+```
+
+</details>
+