wayofdev/nginx repository overview

⁠

⁠Docker Image: Nginx

This Docker image provides a streamlined Nginx setup optimized for local PHP development environments.

It's designed to seamlessly integrate with wayofdev/docker-php-dev⁠ and other (WOD) images, creating an efficient local development ecosystem for web projects.

⁠🌟 Why Choose This Image for Local Development?

• 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

Perfect for developing Laravel applications, Symfony projects, or any PHP-based web services in a local environment that closely mirrors production setups.

Provides foundation for creating, testing, and debugging your web applications locally.

If you like/use this package, please consider ⭐️ starring it. Thanks!

⁠📦 Image Variants

⁠🚀 Usage

⁠→ Pulling the Image

docker pull wayofdev/nginx:k8s-alpine-latest

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:

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}

⁠This configuration includes

• An app service using the wayofdev/php-dev image for PHP processing.
• A web service using a custom Nginx image⁠ 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⁠ repository. This template provides a fully configured development environment for Laravel projects using the wayofdev/php-dev image.

⁠⚙️ Configuration

The Nginx image is pre-configured for optimal performance with PHP applications, but you can customize it further to suit your specific needs.

⁠→ Default Configuration

The default configuration is generated using Ansible templates and includes:

• 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:

   services:
     web:
       image: wayofdev/nginx:k8s-alpine-latest
       environment:
         - PHP_UPSTREAM_CONTAINER=my-php-app
         - PHP_UPSTREAM_PORT=9001
   

   Copy

2. Volume Mounts: For more extensive customizations, you can mount your own config files:

   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
   

   Copy

⁠→ SSL Configuration

The image includes self-signed SSL certificates. To use your own:

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

⁠🔨 Development

This project uses a set of tools for development and testing. The Makefile provides various commands to streamline the development process.

⁠→ Requirements

• Docker
• Make
• Ansible
• goss and dgoss for testing

⁠→ Setting Up the Development Environment

Clone the repository:

git clone [email protected]:wayofdev/docker-nginx.git && \
cd docker-nginx

⁠→ Generating Dockerfiles

Ansible is used to generate Dockerfiles and configurations. To generate distributable Dockerfiles from Jinja template source code:

make generate

⁠→ Building Images

• Build the default image:

  make build
  

  Copy

  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:

  make build IMAGE_TEMPLATE="k8s-alpine"
  

  Copy

  Replace 8.3-fpm-alpine with your desired PHP version, type, and OS.

• Build all images:

  make build IMAGE_TEMPLATE="k8s-alpine"
  make build IMAGE_TEMPLATE="dev-alpine"
  

  Copy

  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⁠, which allows for testing Docker containers.

⁠→ Running Tests

You can run tests using the following commands:

• Test the default image:

  make test
  

  Copy

  This command tests the image specified by the IMAGE_TEMPLATE variable in the Makefile (default is k8s-alpine).

• Test a specific image:

  make test IMAGE_TEMPLATE="k8s-alpine"
  

  Copy

  Replace k8s-alpine with your desired image type, and OS.

• Test all images:

  make test IMAGE_TEMPLATE="k8s-alpine"
  make test IMAGE_TEMPLATE="dev-alpine"
  

  Copy

⁠→ 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

This project has a security policy⁠.

⁠🙌 Want to Contribute?

Thank you for considering contributing to the wayofdev community! We are open to all kinds of contributions. If you want to:

• 🤔 Suggest a feature⁠
• 🐛 Report an issue⁠
• 📖 Improve documentation⁠
• 👨‍💻 Contribute to the code⁠

You are more than welcome. Before contributing, kindly check our contribution guidelines⁠.

⁠🫡 Contributors

⁠

⁠🌐 Social Links

• Twitter: Follow our organization @wayofdev⁠ and the author @wlotyp⁠.
• Discord: Join our community on Discord⁠.

⁠⚖️ License