diff --git a/doc/abuser/README.md b/doc/abuser/README.md new file mode 100644 index 0000000..6afb250 --- /dev/null +++ b/doc/abuser/README.md @@ -0,0 +1,116 @@ +Build your own image + +--- + +

Abuser Documentation

+ + + +### Build your own image + +#### Software Requirements + +You must have the following tools installed locally: +* Python3 +* `PyYAML` Python package (either via pip or OS packet manager) +* `make` +* `docker` + + +#### Other Requirements +You should have a brief understanding about the different flavours available in this repository. + +:information_source: For details see **[README.md#flavours](../../README.md#php-fpm-flavours)**
+:information_source: For details see **[Documentation: Flavours](../flavours.md)** + + +#### How does it work? + +This repository already has all the automation in place. + +1. For each PHP version a `base` image is built to streamline settings across all PHP versions. +2. Based on the `base` image, a `mods` image is built, which only adds a whole bunch of PHP extensions. +3. Based on the `mods` image, a `prod` image is built, which adds features to alter the startup behaviour. +4. Based on the `prod` image, a `work` image is built, which acts as an integrated development environment in which you can actually work (adds a whole bunch of tools). + +What you need to do, is to: + +1. Ensure the `base` image is available locally on your system (either by building it or by pulling it). +2. Decide on the PHP extensions that you want to add +3. Decide on the PHP version you want to build +4. Decide on the architecture/platform you want to build the Docker image for (`amd64` or `arm64`). +5. Build the `mods` image (or just create the Dockerfile for it). + +With this you will be all set, you can however decide to build the `prod` flavour on top of your custom `mods` image as it adds a lot of configurable environment variables to dynamically alter the startup behaviour. + +In case you plan to use your custom image for the **[Devilbox](https://github.com/cytopia/devilbox)**, you must also go ahead and built the `work` flavour on top of the `prod` flavour. + + +#### Generate your custom Dockerfile + +> **Note:** All commands are executed in the root of this repository + +1. Generate PHP extensions in Ansible group_vars + ```bash + # Generate Ansible group_vars for all available extensions + make gen-modules + ``` + ```bash + # Generate Ansible group_vars for selected extensions + # Note: that also all dependent extensions will be added + make gen-modules ARGS="msgpack xsl" + ``` + ```bash + # Generate Ansible group_vars for selected extensions + # and ignore dependencies + make gen-modules ARGS="-i msgpack xsl" + ``` + ```bash + # Show help + make gen-modules ARGS="--help" + ``` +2. Generate Dockerfiles from Ansible group_vars + ```bash + make gen-dockerfiles + ``` + + +#### Build your custom Dockerfile + +> **Note:** All commands are executed in the root of this repository + +1. Ensure you have the `base` image locally for your desired version and architecture + ```bash + ARCH=linux/amd64 + VERSION=8.1 + make docker-pull-base-image STAGE=mods VERSION=${VERSION} ARCH=${ARCH} + ``` +2. Build the `mods` image + ```bash + ARCH=linux/amd64 + VERSION=8.1 + make build STAGE=mods VERSION=${VERSION} ARCH=${ARCH} + ``` +3. (Optional) Build the `prod` image + ```bash + ARCH=linux/amd64 + VERSION=8.1 + make build STAGE=prod VERSION=${VERSION} ARCH=${ARCH} + ``` +4. (Optional) Build the `work` image + ```bash + ARCH=linux/amd64 + VERSION=8.1 + make build STAGE=work VERSION=${VERSION} ARCH=${ARCH} + ``` + + +#### FAQ + +1. Where do I find the generated Dockerfile? +2. How can I omit dependent PHP extensions when generating the Dockerfile? +3. How do I ensure that dependent PHP extensions are automatically added to the Dockerfile? +4. Where do I see what PHP extensions are available in this repository? +5. How do I know what each of the provided PHP extensions is for? +6. How can I add PHP extensions that are not provided here? +7. Switching architectures fails with errors, what should I do?