From 3641552483bae54b66f23542401fc9757d1da908 Mon Sep 17 00:00:00 2001
From: Alexander Schranz <alexander@sulu.io>
Date: Thu, 3 Nov 2022 09:04:29 +0100
Subject: [PATCH] docs: building Docker images (#75)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add docs for custom docker image

* docs: improve Docker documentation

* more docs

Co-authored-by: Kévin Dunglas <kevin@dunglas.fr>
---
 CONTRIBUTING.md | 31 +++++++++++++++++++
 README.md       |  3 +-
 docs/docker.md  | 80 +++++++++++++++++++++++++++++++++++++++----------
 3 files changed, 98 insertions(+), 16 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a4cc97a..9e3f402 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -52,6 +52,32 @@ The server is listening on `127.0.0.1:8080`:
 
     curl -v http://127.0.0.1:8080/phpinfo.php
 
+# Building Docker Images Locally
+
+Print bake plan:
+
+```
+docker buildx bake -f docker-bake.hcl --print
+```
+
+Build FrankenPHP images for amd64 locally:
+
+```
+docker buildx bake -f docker-bake.hcl --pull --load --set "*.platform=linux/amd64"
+```
+
+Build FrankenPHP images for arm64 locally:
+
+```
+docker buildx bake -f docker-bake.hcl --pull --load --set "*.platform=linux/arm64"
+```
+
+Build FrankenPHP images from scratch for arm64 & amd64 and push to Docker Hub:
+
+```
+docker buildx bake -f docker-bake.hcl --pull --no-cache --push
+```
+
 ## Misc Dev Resources
 
 * [PHP embedding in uWSGI](https://github.com/unbit/uwsgi/blob/master/plugins/php/php_plugin.c)
@@ -63,3 +89,8 @@ The server is listening on `127.0.0.1:8080`:
 * [What the heck is TSRMLS_CC, anyway?](http://blog.golemon.com/2006/06/what-heck-is-tsrmlscc-anyway.html)
 * [PHP embedding on Mac](https://gist.github.com/jonnywang/61427ffc0e8dde74fff40f479d147db4)
 * [SDL bindings](https://pkg.go.dev/github.com/veandco/go-sdl2@v0.4.21/sdl#Main)
+
+## Docker-Related Resources
+
+* [Bake file definition](https://docs.docker.com/build/customize/bake/file-definition/)
+* [docker buildx build](https://docs.docker.com/engine/reference/commandline/buildx_build/)
diff --git a/README.md b/README.md
index e42942e..5192950 100644
--- a/README.md
+++ b/README.md
@@ -34,8 +34,9 @@ Go to `https://localhost`, and enjoy!
 * [Early Hints support (103 HTTP status code)](docs/early-hints.md)
 * [Real-time](docs/mercure.md)
 * [Configuration](docs/config.md)
+* [Docker images](docs/docker.md)
 * [Compile from sources](docs/compile.md)
-* [Building Docker images](docs/docker.md)
+* [Demo app (Symfony) and benchmarks](https://github.com/dunglas/frankenphp-demo)
 * [Go library documentation](https://pkg.go.dev/github.com/dunglas/frankenphp)
 * [Contributing and debugging](CONTRIBUTING.md)
 
diff --git a/docs/docker.md b/docs/docker.md
index bdd67b3..c3e3bc5 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -1,30 +1,80 @@
-# Building Docker Images
+# Building Custom Docker Image
 
-Print bake plan:
+[FrankenPHP Docker images](https://hub.docker.com/repository/docker/dunglas/frankenphp) are based on [official PHP images](https://hub.docker.com/_/php/). Alpine Linux and Debian variants are provided for popular architectures.
 
-```
-docker buildx bake -f docker-bake.hcl --print
+## How to Use The Images
+
+Create a `Dockerfile` in your project:
+
+```Dockerfile
+FROM dunglas/frankenphp
+
+COPY . /app/public
 ```
 
-Build FrankenPHP images for amd64 locally:
+Then, run the commands to build and run the Docker image:
 
 ```
-docker buildx bake -f docker-bake.hcl --pull --load --set "*.platform=linux/amd64"
+$ docker build -t my-php-app .
+$ docker run -it --rm --name my-running-app my-php-app
 ```
 
-Build FrankenPHP images for arm64 locally:
+## How to Install More PHP Extensions
 
-```
-docker buildx bake -f docker-bake.hcl --pull --load --set "*.platform=linux/arm64"
+The [`docker-php-extension-installer`](https://github.com/mlocati/docker-php-extension-installer) script is provided in the base image.
+Adding additional PHP extensions is straightforwardd:
+
+```dockerfile
+FROM dunglas/frankenphp
+
+# add additional extensions here:
+RUN install-php-extensions \
+    pdo_mysql \
+    gd \
+    intl \
+    zip \
+    opcache
+
+# ...
 ```
 
-Build FrankenPHP images from scratch for arm64 & amd64 and push to Docker Hub:
+# Enabling the Worker Mode by Default
 
-```
-docker buildx bake -f docker-bake.hcl --pull --no-cache --push
+Set the `FRANKENPHP_CONFIG` environment variable to start FrankenPHP with a worker script:
+
+```Dockerfile
+FROM dunglas/frankenphp
+
+# ...
+
+ENV FRANKENPHP_CONFIG="worker ./public/index.php"
 ```
 
-## Resources
+# Using a Volume in Development
 
-* [Bake file definition](https://docs.docker.com/build/customize/bake/file-definition/)
-* [docker buildx build](https://docs.docker.com/engine/reference/commandline/buildx_build/)
+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:
+
+```
+docker run -v $PWD:/app/public -p 80:80 -p 443:443 my-php-app
+```
+
+With Docker Compose:
+
+```yaml
+# docker-compose.yml
+
+version: '3.1'
+
+services:
+
+  php:
+    image: dunglas/frankenphp
+    # uncomment the following line if you want to use a custom Dockerfile
+    #build: .
+    restart: always
+    ports:
+      - 80:80
+      - 443:443
+    volumes:
+      - ./:/app/public
+```