From 9450615d4034c1252a0f60c053eb5ba01142474e Mon Sep 17 00:00:00 2001 From: lotyp Date: Fri, 13 Sep 2024 14:01:53 +0300 Subject: [PATCH] docs: update README --- README.md | 297 +++++++++++++++++++++++++++++++++++------ src/group_vars/all.yml | 4 - 2 files changed, 255 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index ceb2be8..11aa88e 100644 --- a/README.md +++ b/README.md @@ -21,90 +21,303 @@ # Docker Image: Nginx -This image is used together with [wayofdev/docker-php-dev](https://github.com/wayofdev/docker-php-dev) and other WOD images, to create local development environment for our projects. +This **Docker image** provides a streamlined **Nginx** setup optimized for **local PHP development environments**. -![Screenshot](.github/assets/screenshot.png) +It's designed to seamlessly integrate with [wayofdev/docker-php-dev](https://github.com/wayofdev/docker-php-dev) and other (WOD) images, creating an efficient local development ecosystem for web projects. -## โš™๏ธ Development +
+ +## ๐ŸŒŸ Why Choose This Image for Local Development? -To install dependencies and start development you can check contents of our `Makefile` +- **Ansible-based Configuration:** Easily customizable through Ansible templates +- **PHP-FPM Optimized:** Pre-configured to work with PHP-FPM for fast local testing and development +- **SSL Ready:** Includes built-in support for HTTPS using self-signed certificates, mimicking production environments locally +- **Developer Friendly:** Packed with tools and configurations to enhance local development workflows +- **Flexible Deployment:** Includes a `k8s-alpine` variant for testing Kubernetes setups locally +- **Lightweight:** Based on **Alpine Linux** for minimal footprint and faster local builds +- **Multi-arch Support:** Works on both **x86 (AMD64)** and **ARM64** architectures, supporting various development machines +- **Regular Updates:** Maintained and updated frequently to align with the latest development practices -### โ†’ Requirements +Perfect for developing **Laravel** applications, **Symfony** projects, or any **PHP-based web services** in a local environment that closely mirrors production setups. -For testing purposes we use **goss** and **dgoss**, follow installation instructions on [their official README](https://github.com/aelsabbahy/goss/blob/master/extras/dgoss/README.md) +Provides foundation for creating, testing, and debugging your web applications locally.
-### โ†’ Building locally +If you **like/use** this package, please consider โญ๏ธ **starring** it. Thanks! -Generating distributable Dockerfiles from yaml source code: +
-```bash -make generate -``` +## ๐Ÿ“ฆ Image Variants + +| Variant | Description | +|------------|-------------------------------------------------------------------------------| +| dev-alpine | For local development environments, uses 80 and 443 ports. | +| k8s-alpine | Optimized for k8s and local environments, uses 8880 and 8443 ports, rootless. |
-Building default image: +## ๐Ÿš€ Usage + +### โ†’ Pulling the Image ```bash -git clone git@github.com:wayofdev/docker-nginx.git -cd docker-nginx -make build +docker pull wayofdev/nginx:k8s-alpine-latest ``` -To **build** image, **test** it and then **clean** temporary files run: - -```bash -make +Replace `k8s-alpine-latest` with your desired type, and tag. + +### โ†’ Available Image Variants + +- **Types:** k8s, dev +- **Architectures:** amd64, arm64 + +### โ†’ Using in Docker Compose + +Here's an example `docker-compose.yml` for a typical setup: + +```yaml +services: + app: + image: wayofdev/php-dev:8.3-fpm-alpine-latest + container_name: ${COMPOSE_PROJECT_NAME}-app + restart: on-failure + networks: + - default + - shared + depends_on: + - database + links: + - database + volumes: + - ./.github/assets:/assets:rw,cached + - ./app:/app:rw,cached + - ./.env:/app/.env + - ~/.composer:/.composer + - ~/.ssh:/home/www-data/.ssh + environment: + FAKETIME: '+2h' + XDEBUG_MODE: '${XDEBUG_MODE:-off}' + PHIVE_HOME: /app/.phive + dns: + - 8.8.8.8 + extra_hosts: + - 'host.docker.internal:host-gateway' + + web: + image: wayofdev/nginx:k8s-alpine-latest + container_name: ${COMPOSE_PROJECT_NAME}-web + restart: on-failure + networks: + - default + - shared + depends_on: + - app + links: + - app + volumes: + - ./app:/app:rw,cached + - ./.env:/app/.env + labels: + - traefik.enable=true + - traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.rule=Host(`api.${COMPOSE_PROJECT_NAME}.docker`) + - traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.entrypoints=websecure + - traefik.http.routers.api-${COMPOSE_PROJECT_NAME}-secure.tls=true + - traefik.http.services.api-${COMPOSE_PROJECT_NAME}-secure.loadbalancer.server.port=8880 + - traefik.docker.network=network.${SHARED_SERVICES_NAMESPACE} ``` -Building all images: +#### This configuration includes -```bash -make build IMAGE_TEMPLATE=dev-alpine -make build IMAGE_TEMPLATE=k8s-alpine -``` +- An `app` service using the `wayofdev/php-dev` image for PHP processing. +- A `web` service using a [custom Nginx image](https://github.com/wayofdev/docker-nginx) for serving the application. +- Network configuration for both default and shared networks. +- Volume mounts for application code, assets, and configuration files. +- Environment variables for PHP and Xdebug configuration. +- Traefik labels for reverse proxy and SSL termination. + +#### Real-world Example + +For a comprehensive, real-world example of how to use this image in a Docker Compose setup, please refer to the [wayofdev/laravel-starter-tpl](https://github.com/wayofdev/laravel-starter-tpl) repository. This template provides a fully configured development environment for Laravel projects using the `wayofdev/php-dev` image.
-## ๐Ÿงช Testing +## โš™๏ธ Configuration -Testing default image: +The Nginx image is pre-configured for optimal performance with PHP applications, but you can customize it further to suit your specific needs. -```bash -make test -``` +### โ†’ Default Configuration -To test all images: +The default configuration is generated using Ansible templates and includes: -```bash -make test IMAGE_TEMPLATE=dev-alpine -make test IMAGE_TEMPLATE=k8s-alpine +- Optimized settings for PHP-FPM +- SSL/TLS support with self-signed certificates +- Gzip compression enabled +- Basic security headers + +### โ†’ Custom Configuration + +While the configuration is primarily managed through Ansible templates, you can override specific settings: + +1. **Environment Variables:** The image uses the following environment variables: + + | Variable | Default Value | Description | + |------------------------|---------------|---------------------------------------| + | PHP_UPSTREAM_CONTAINER | app | The name of the PHP-FPM container | + | PHP_UPSTREAM_PORT | 9000 | The port of the PHP-FPM container | + + Set these in your `docker-compose.yml` file: + + ```yaml + services: + web: + image: wayofdev/nginx:k8s-alpine-latest + environment: + - PHP_UPSTREAM_CONTAINER=my-php-app + - PHP_UPSTREAM_PORT=9001 + ``` + +2. **Volume Mounts:** For more extensive customizations, you can mount your own config files: + + ```yaml + services: + web: + image: wayofdev/nginx:k8s-alpine-latest + volumes: + - ./custom-nginx.conf:/etc/nginx/nginx.conf + - ./custom-default.conf:/etc/nginx/conf.d/default.conf + ``` + +### โ†’ SSL Configuration + +The image includes self-signed SSL certificates. To use your own: + +```yaml +services: + web: + image: wayofdev/nginx:k8s-alpine-latest + volumes: + - ./certs/cert.pem:/etc/nginx/ssl/cert.pem + - ./certs/key.pem:/etc/nginx/ssl/key.pem ``` +### โ†’ Advanced Configuration + +For more advanced configurations: + +1. Fork this repository +2. Modify the Ansible templates in the `src` directory +3. Regenerate the Dockerfiles using `make generate` +4. Build your custom image +
-### โ†’ Code quality tools +## ๐Ÿ”จ Development -Run **yamllint** to validate all yaml files in project: +This project uses a set of tools for development and testing. The `Makefile` provides various commands to streamline the development process. -```bash -make lint-yaml -``` +### โ†’ Requirements + +- Docker +- Make +- Ansible +- goss and dgoss for testing -Run hadolint to validate created Dockerfiles: +### โ†’ Setting Up the Development Environment + +Clone the repository: ```bash -make lint-docker +git clone git@github.com:wayofdev/docker-nginx.git && \ +cd docker-nginx ``` -Run ansible-lint to validate project files: +### โ†’ Generating Dockerfiles + +Ansible is used to generate Dockerfiles and configurations. To generate distributable Dockerfiles from Jinja template source code: ```bash -make lint-ansible +make generate ``` +### โ†’ Building Images + +- Build the default image: + + ```bash + make build + ``` + + This command builds the image specified by the `IMAGE_TEMPLATE` variable in the Makefile. By default, it's set to `k8s-alpine`. + +- Build a specific image: + + ```bash + make build IMAGE_TEMPLATE="k8s-alpine" + ``` + + Replace `8.3-fpm-alpine` with your desired PHP version, type, and OS. + +- Build all images: + + ```bash + make build IMAGE_TEMPLATE="k8s-alpine" + make build IMAGE_TEMPLATE="dev-alpine" + ``` + + These commands will build all supported image variants. + +
+ +## ๐Ÿงช Testing + +This project uses a testing approach to ensure the quality and functionality of the Docker images. The primary testing tool is [dgoss](https://github.com/aelsabbahy/goss/tree/master/extras/dgoss), which allows for testing Docker containers. + +### โ†’ Running Tests + +You can run tests using the following commands: + +- Test the default image: + + ```bash + make test + ``` + + This command tests the image specified by the `IMAGE_TEMPLATE` variable in the Makefile (default is `k8s-alpine`). + +- Test a specific image: + + ```bash + make test IMAGE_TEMPLATE="k8s-alpine" + ``` + + Replace `8.3-fpm-alpine` with your desired PHP version, type, and OS. + +- Test all images: + + ```bash + make test IMAGE_TEMPLATE="k8s-alpine" + make test IMAGE_TEMPLATE="dev-alpine" + ``` + +### โ†’ Test Configuration + +The test configurations are defined in `goss.yaml` files, which are generated for each image variant. These files specify the tests to be run, including: + +- File existence and permissions +- Process checks +- Port availability +- Package installations +- Command outputs + +### โ†’ Test Process + +When you run the `make test` command, the following steps occur: + +1. The specified Docker image is built (if not already present). +2. dgoss runs the tests defined in the `goss.yaml` file against the Docker container. +3. The test results are displayed in the console. +
## ๐Ÿ”’ Security Policy diff --git a/src/group_vars/all.yml b/src/group_vars/all.yml index d6e299c..2705afb 100644 --- a/src/group_vars/all.yml +++ b/src/group_vars/all.yml @@ -27,16 +27,12 @@ tpl_dockerfiles: # Additional configuration files ######################################################################################################################## tpl_configs: - # 00-set-upstream.sh - src: config/00-set-upstream.sh.j2 dst: "../dist/{{ level }}-{{ os_name }}/configs/00-set-upstream.sh" - # 00_upstream.conf - src: config/00_upstream.conf.j2 dst: "../dist/{{ level }}-{{ os_name }}/configs/00_upstream.conf" - ## default.conf - src: config/default.conf.j2 dst: "../dist/{{ level }}-{{ os_name }}/configs/default.conf" - ## nginx.conf - src: config/nginx.conf.j2 dst: "../dist/{{ level }}-{{ os_name }}/configs/nginx.conf"