docs: improve HTTPS documentation (#480)

dunglas · Jan 20, 2024 · b624a13 · b624a13
1 parent 00b1d0e
commit b624a13
Show file tree

Hide file tree

Showing 8 changed files with 75 additions and 20 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,7 +8,7 @@ Build the dev Docker image:
 
 ```console
 docker build -t frankenphp-dev -f dev.Dockerfile .
-docker run --cap-add=SYS_PTRACE --security-opt seccomp=unconfined -p 8080:8080 -p 443:443 -v $PWD:/go/src/app -it frankenphp-dev
+docker run --cap-add=SYS_PTRACE --security-opt seccomp=unconfined -p 8080:8080 -p 443:443 -p 443:443/udp -v $PWD:/go/src/app -it frankenphp-dev
 ```
 
 The image contains the usual development tools (Go, GDB, Valgrind, Neovim...).  

diff --git a/README.md b/README.md
@@ -20,15 +20,16 @@ FrankenPHP can also be used as a standalone Go library to embed PHP in any app u
 
 ```console
 docker run -v $PWD:/app/public \
-    -p 80:80 -p 443:443 \
+    -p 80:80 -p 443:443 -p 443:443/udp \
     dunglas/frankenphp
 ```
 
 Go to `https://localhost`, and enjoy!
 
 > [!TIP]
 >
-> Do not attempt to use `https://127.0.0.1`. Use `localhost` and accept the self-signed certificate. Caddy has an automatic TLS handling that auto-trusts some local-based hostnames like `localhost`, but it does not apply to IP addresses. More details [on Caddy's "automatic https" docs](https://caddyserver.com/docs/automatic-https#hostname-requirements).
+> Do not attempt to use `https://127.0.0.1`. Use `localhost` and accept the self-signed certificate.
+> Use the [`SERVER_NAME` environment variable](docs/config.md#environment-variables) to change the domain to use.
 
 ### Standalone Binary
 

diff --git a/docs/config.md b/docs/config.md
@@ -131,7 +131,7 @@ php_server [<matcher>] {
 
 The following environment variables can be used to inject Caddy directives in the `Caddyfile` without modifying it:
 
-* `SERVER_NAME` change the server name
+* `SERVER_NAME`: change [the addresses on which to listen](https://caddyserver.com/docs/caddyfile/concepts#addresses), the provided hostnames will also be used for the generated TLS certificate
 * `CADDY_GLOBAL_OPTIONS`: inject [global options](https://caddyserver.com/docs/caddyfile/options)
 * `FRANKENPHP_CONFIG`: inject config under the `frankenphp` directive
 
@@ -146,6 +146,6 @@ When using the Docker image, set the `CADDY_GLOBAL_OPTIONS` environment variable
 ```console
 docker run -v $PWD:/app/public \
     -e CADDY_GLOBAL_OPTIONS=debug \
-    -p 80:80 -p 443:443 \
+    -p 80:80 -p 443:443 -p 443:443/udp \
     dunglas/frankenphp
 ```
diff --git a/docs/docker.md b/docs/docker.md
@@ -92,9 +92,13 @@ ENV FRANKENPHP_CONFIG="worker ./public/index.php"
 To develop easily with FrankenPHP, mount the directory from your host containing the source code of the app as a volume in the Docker container:
 
 ```console
-docker run -v $PWD:/app/public -p 80:80 -p 443:443 my-php-app
+docker run -v $PWD:/app/public -p 80:80 -p 443:443 -p 443:443/udp --tty my-php-app
 ```
 
+> ![TIP]
+>
+> The `--tty` option allows to have nice human-readable logs instead of JSON logs.
+
 With Docker Compose:
 
 ```yaml
@@ -108,8 +112,9 @@ services:
     # uncomment the following line if you want to run this in a production environment
     # restart: always
     ports:
-      - 80:80
-      - 443:443
+      - "80:80" # HTTP
+      - "443:443" # HTTPS
+      - "443:443/udp" # HTTP/3
     volumes:
       - ./:/app/public
       - caddy_data:/data

diff --git a/docs/known-issues.md b/docs/known-issues.md
@@ -41,3 +41,54 @@ The following extensions are known not to be compatible with FrankenPHP:
 ## get_browser
 
 The [get_browser](https://www.php.net/manual/en/function.get-browser.php) function seems to have a bad performance after a while. A workaround is to cache (e.g. with APCU) the results per User Agent, as they are static anyway.
+
+## Using `https://127.0.0.1` with Docker
+
+By default, FrankenPHP generates a TLS certificate for `localhost`.
+It's the easiest and recommended option for local development.
+
+If you really want to use `127.0.0.1` as a host instead, it's possible to configure it to generate a certificate for it by setting the server name to `127.0.0.1`.
+
+Unfortunately, this is not enough when using Docker because of [its networking system](https://docs.docker.com/network/).
+You will get a TLS error similar to `curl: (35) LibreSSL/3.3.6: error:1404B438:SSL routines:ST_CONNECT:tlsv1 alert internal error`.
+
+If you're using Linux, a solution is to use [the host networking driver](https://docs.docker.com/network/network-tutorial-host/):
+
+```console
+docker run \
+    -e SERVER_NAME="127.0.0.1" \
+    -v $PWD:/app/public \
+    --network host \
+    dunglas/frankenphp
+```
+
+The host networking driver isn't supported on Mac and Windows. On these platforms, you will have to guess the IP address of the container, and include it in the server names.
+
+Run the `docker network inspect bridge` and look at the `Containers` key to identify the last currently assigned IP address under the `IPv4Address` key, and increment it by one. If no container is running, the first assigned IP address is usually `172.17.0.2`.
+
+Then, include this in the `SERVER_NAME` environment variable:
+
+```console
+docker run \
+    -e SERVER_NAME="127.0.0.1, 172.17.0.3" \
+    -v $PWD:/app/public \
+    -p 80:80 -p 443:443 -p 443:443/udp \
+    dunglas/frankenphp
+```
+
+> ![CAUTION]
+>
+> Be sure to replace `172.17.0.3` by the IP that will be assigned to your container.
+
+You should now be able to access to `https://127.0.0.1` from the host machine.
+
+If it's not the case, start FrankenPHP in debug mode to try to figure out the problem:
+
+```console
+docker run \
+    -e CADDY_GLOBAL_OPTIONS="debug"
+    -e SERVER_NAME="127.0.0.1" \
+    -v $PWD:/app/public \
+    -p 80:80 -p 443:443 -p 443:443/udp \
+    dunglas/frankenphp
+```
diff --git a/docs/laravel.md b/docs/laravel.md
@@ -7,7 +7,7 @@ Serving a [Laravel](https://laravel.com) web application with FrankenPHP is as e
 Run this command from the main directory of your Laravel app:
 
 ```console
-docker run -p 443:443 -v $PWD:/app dunglas/frankenphp
+docker run -p 80:80 -p 443:443 -p 443:443/udp -v $PWD:/app dunglas/frankenphp
 ```
 
 And enjoy!
@@ -74,6 +74,4 @@ php artisan octane:start
 {--log-level= : Log messages at or above the specified log level}';
 ```
 
-## Docs
-
-* [Laravel Octane](https://laravel.com/docs/master/octane)
+Learn more about [Laravel Octane in its official documentation](https://laravel.com/docs/octane).
diff --git a/docs/production.md b/docs/production.md
@@ -41,9 +41,9 @@ services:
     image: dunglas/frankenphp
     restart: always
     ports:
-      - "80:80/tcp" # HTTP
-      - "443:443/tcp" # HTTPS
-      - "443:443/udp" # # HTTP/3
+      - "80:80" # HTTP
+      - "443:443" # HTTPS
+      - "443:443/udp" # HTTP/3
     volumes:
       - caddy_data:/data
       - caddy_config:/config

diff --git a/docs/worker.md b/docs/worker.md
@@ -13,7 +13,7 @@ Set the value of the `FRANKENPHP_CONFIG` environment variable to `worker /path/t
 docker run \
     -e APP_RUNTIME=Runtime\\FrankenPhpSymfony\\Runtime \
     -v $PWD:/app \
-    -p 80:80 -p 443:443 \
+    -p 80:80 -p 443:443 -p 443:443/udp \
     dunglas/frankenphp
 ```
 
@@ -41,13 +41,13 @@ docker run \
     -e FRANKENPHP_CONFIG="worker ./public/index.php" \
     -e APP_RUNTIME=Runtime\\FrankenPhpSymfony\\Runtime \
     -v $PWD:/app \
-    -p 80:80 -p 443:443 \
+    -p 80:80 -p 443:443 -p 443:443/udp \
     dunglas/frankenphp
 ```
 
 ## Laravel Octane
 
-See [this Pull Request](https://github.com/laravel/octane/pull/764).
+See [the dedicated documentation](laravel.md#laravel-octane).
 
 ## Custom Apps
 
@@ -91,7 +91,7 @@ Then, start your app and use the `FRANKENPHP_CONFIG` environment variable to con
 docker run \
     -e FRANKENPHP_CONFIG="worker ./public/index.php" \
     -v $PWD:/app \
-    -p 80:80 -p 443:443 \
+    -p 80:80 -p 443:443 -p 443:443/udp \
     dunglas/frankenphp
 ```
 
@@ -102,7 +102,7 @@ You can also configure the number of workers to start:
 docker run \
     -e FRANKENPHP_CONFIG="worker ./public/index.php 42" \
     -v $PWD:/app \
-    -p 80:80 -p 443:443 \
+    -p 80:80 -p 443:443 -p 443:443/udp \
     dunglas/frankenphp
 ```