🐳 NPP Dockerized

Welcome to the Docker project optimized for the (NPP) WordPress Plugin! 🎉 This full-stack Dockerized environment is designed for NPP, including WordPress with FPM, Nginx, MySQL, FastCGI Cache, WP-CLI, phpMyAdmin, Redis, mitmproxy and necessary PHP extensions. It's tailored for easy deployment and efficient use of the NPP plugin

Explore the NPP Main GitHub Repository to access the heart of the plugin development.

✨ Features

• ✅ WordPress (7.1) with PHP-FPM (8.4)
• ✅ MySQL (8.4) for database management
• ✅ Nginx FastCGI cache ready with (Nginx 1.31.6 + ngx_cache_purge v3.0.3 + ngx_headers_more v0.39)
• ✅ Redis (7.4) for object caching and session management
• ✅ WP-CLI ready for plugin and theme installations (check .env)
• ✅ phpMyAdmin (5.2.3) ready
• ✅ Nginx cache optimised for WooCommerce
• ✅ Includes all system dependencies required for the NPP plugin
• ✅ Isolated and secure PHP process owner for enhanced security and performance
• ✅ Built with bindfs (1.18.4) + fuse3 (3.18.3) for FUSE-based mounting of Nginx Cache Path
• ✅ Installed a wide range of PHP extensions
• ✅ Easily switch between the stable release and the bleeding-edge version of the NPP
• ✅ ripgrep (15.2.0) installed RG Purge for blazing fast single URL purges
• ✅ safexec (1.9.6) installed for hardened, privilege-dropped cache preload shell execution
• ✅ mitmproxy sidecar for full NPP plugin feature testing including Proxy Preload

🔒 Security & Proxy Features

safexec (Default: Enabled)

safexec is a setuid-root binary that drops privileges before executing shell commands. It ensures that wget-based cache preload processes run as an isolated user instead of the PHP-FPM process owner, hardening the environment against privilege escalation.

NPP_SAFEXEC_ENABLED=1  # Enable (default)
NPP_SAFEXEC_ENABLED=0  # Disable at runtime without rebuilding

safexec is installed at build time. Set INSTALL_SAFEXEC=false as a build arg to skip installation entirely.

---

mitmproxy — Full Plugin Feature Testing

This stack includes a dedicated mitmproxy sidecar container (npp-mitm) so you can test the complete NPP plugin feature set, including the Proxy Preload feature, end-to-end in a local Docker environment.

Toggle at runtime:

NPP_MITM_ENABLED=1  # Enable (default)
NPP_MITM_ENABLED=0  # Disable

NPP Plugin settings are auto-configured via WP-CLI on first startup:

Setting	Value
Nginx Cache Path	/var/cache/nginx-npp (FUSE mount)
Preload Watchdog	Enabled
HTTP Purge	Enabled
HTTP Purge Base URL	https://nginx/purge
Proxy Host	npp-mitm
Proxy Port	3434

🔑 Environment Variables

This repository was primarily created for testing and developing the NPP plugin on local. However, with minor adjustments, It can also be used as a production environment.

Please check the .env file for the environment variables used in the project. Some variables can be directly modified by the user for easy customization, while others are derived from the original Dockerfiles of core services. Changing these core variables for a production environment may require adjustments in other parts of the project to maintain seamless integration and workflow. Feel free to customize it to suit your full-stack WordPress production needs!

Use the Bleeding-Edge Version of NPP (Default)

If you want to use the latest bleeding-edge version of the NPP plugin simply set the following environment variable:

NPP_EDGE=1

🔄 This will sync the plugin with the latest development branch commit from GitHub, ensuring you always have access to the newest features and improvements.

⚠️ In Production

To enable Nginx Cache Preload in a localhost development environment, a small host configuration adjustment is always required. In production, this may or may not be required depending on your Docker architecture. If you encounter a Cache Preload issue in production, try enabling the below setting in .env, otherwise, you can disable it entirely.

NPP_HACK_HOST=1

For a full explanation and to adjust your environment, please read the complete story here:

wordpress-nginx-cache-docker/wordpress/wp-post.sh

Line 129 in 1c8043a

# To enable NPP Plugin Nginx Cache Preload action:

⚙️️ Instant Deployment

1. Clone the repository

Start by cloning the repository to your local machine:

git clone https://github.com/psaux-it/wordpress-nginx-cache-docker.git
cd wordpress-nginx-cache-docker

2. Configure environment

Copy the example environment file and adjust it to your own setup (passwords, admin credentials, host, etc. — see the .env section above for details):

cp .env.example .env

⚠️ Do not skip this. The default .env.example values (passwords, WordPress admin credentials) are placeholders only and must be changed before any production deployment.

3. Run the Services

Run the following command to build and start the container:

• Using pre-built images:

docker compose up

• Building locally:

docker compose up --build

🚀 Post-Container Startup Access

• The WordPress site can be accessed at the host machine:

  • 🔒 https://localhost
  • 🌐 http://localhost

• Default WordPress wp-admin login credentials:

  • Username: npp
  • Password: npp

• You can also access phpMyAdmin at:

  • https://localhost/phpmyadmin

• Default FUSE mount path:

  • /var/cache/nginx-npp
  • Use the FUSE mount path as the Nginx cache path in the NPP plugin settings page.

🧪 Fail2Ban E2E Lab (actionstart-fail2ban.sh)

A helper script that spins up everything needed to run the NPP Fail2ban-test end-to-end suite inside this stack. It tests how the plugin handles incoming fail2ban bans (queueing, RIPEstat whois/abuse lookups, retries, rate limits) without touching the real stat.ripe.net. A fake RIPEstat server is used instead.

What it does

• Starts the stack with docker-compose.lab.yml, which maps stat.ripe.net to 127.0.0.2 inside wordpress-fpm and mounts the npp_lab volume.
• Waits for WordPress and the NPP plugin (minimum version 2.1.8).
• Installs the needed tooling in wordpress-fpm, creates a lab CA, and installs the f2b-lab mu-plugin.
• Runs the test phases (happy, faults, optional ratelimit) and prints a pass/fail summary.

Usage (run on the Docker host, from the directory containing docker-compose.yml)

./actionstart-fail2ban.sh                       # prepare everything and run all phases
./actionstart-fail2ban.sh --only happy,faults   # run selected phases
./actionstart-fail2ban.sh --with-ratelimit      # also run the ratelimit phase
./actionstart-fail2ban.sh --count 100           # more IPs in the happy phase
./actionstart-fail2ban.sh --build               # rebuild images while bringing the stack up
./actionstart-fail2ban.sh --no-run              # prepare only, don't run the tests
./actionstart-fail2ban.sh --shell               # root shell in the lab directory

Cleanup

./actionstart-fail2ban.sh --clean   # stop fake RIPEstat, remove mu-plugin + lab CA
./actionstart-fail2ban.sh --purge   # --clean + delete pki/ and run/, drop the lab hosts override

--purge recreates the wordpress container, so python3 is reinstalled on the next run.

Optional environment overrides: C, WP_USER, SITE_URL, WP_PATH, LAB_DIR, MIN_NPP, WAIT (see the header of the script for defaults).

---

⚠️ Important Notices

🚨 The included SSL certificates are dummy, strictly for local usage and must not be used in production environments.
📦 This project leverages the fantastic work by Michele Locati to streamline the installation of required PHP extensions.