Docker Compose Builder · WordPress / MariaDB + Redis

Docker Compose WordPress + MariaDB 11 + Redis + Nginx Healthcheck Guide

Generate a Compose Specification docker-compose.yml and matching .env.example for WordPress / MariaDB + Redis with native binary healthchecks, service_healthy boot ordering, and firewall-safe port bindings.

Written & verified by Chathura Prabashana · Updated November 2026

1. Adjust stack settings or load a test scenario2. Inspect live diagnostics3. Copy generated config
Quick-Test Scenarios:

1. Runtime & Data Services

2. Healthchecks, Workers & Security

# docker-compose.yml — Modern Compose Specification (no obsolete 'version:' attribute)
# Generated by OpsCheck DevTools (Laravel PHP)
name: wordpress_mariadb_stack

services:
  wordpress:
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    env_file:
      - .env
    expose:
      - "9000"
    environment:
      DB_HOST: mariadb
      DB_PORT: "3306"
      REDIS_HOST: redis
      REDIS_PORT: "6379"
    depends_on:
      mariadb:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - app_network

  nginx:
    image: nginx:1.27-alpine
    restart: unless-stopped
    ports:
      - "127.0.0.1:80:80"
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - wordpress
    networks:
      - app_network

  mariadb:
    image: mariadb:11
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: ${DB_DATABASE:-app_db}
      MARIADB_USER: ${DB_USERNAME:-app}
      MARIADB_PASSWORD: ${DB_PASSWORD:-change_me_strong}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:-root_change_me}
    # Kept strictly internal on app_network (prevents Docker iptables UFW bypass)
    expose:
      - "3306"
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
    networks:
      - app_network

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    restart: unless-stopped
    expose:
      - "6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    networks:
      - app_network

networks:
  app_network:
    driver: bridge

volumes:
  db_data:
  redis_data:
Service Boot Orderbridge: app_network
mariadb(healthy)+redis(healthy)wordpressnginx

Healthcheck & Security Diagnostics

Compose Spec v2+
  • passStartup Race Condition Prevented (condition: service_healthy)

    wordpress will wait until mariadb and redis pass their native healthchecks before starting.

  • infoInternal Bridge DNS Hostnames (Never Use localhost Inside Containers)

    Connect over the shared app_network using Docker service names: DB_HOST=mariadb (port 3306), REDIS_HOST=redis (port 6379). Inside the "wordpress" container, 127.0.0.1/localhost points only to "wordpress" itself and always refuses DB/broker connections.

  • passFirewall-Safe Port Exposure Enabled (127.0.0.1 / Internal expose:)

    Database and broker ports stay strictly isolated on app_network via expose:, and app ports bind to 127.0.0.1 so Docker never bypasses host UFW/nftables rules.

  • passNative Probe Binaries Used (healthcheck.sh --connect --innodb_initialized & redis-cli ping)

    Generated healthchecks invoke built-in service binaries rather than curl or wget, avoiding false "unhealthy" states in minimal Alpine and slim official images.

  • passPersistent Named Volumes Declared (db_data, redis_data)

    Top-level named volumes preserve database tables and broker queues across container rebuilds and "docker compose down" (data is only removed if you pass -v).

Runs locally in your browser. Compose YAML and environment templates are generated client-side.

Typical Container Boot & Connection Error (WordPress / MariaDB + Redis)

When depends_on lacks condition: service_healthy or internal service hostnames are misconfigured in .env, container logs typically surface this error during startup:

docker compose logs (Startup Failure)

Warning: mysqli_real_connect(): (HY000/2002): Connection refused in /var/www/html/wp-includes/class-wpdb.php on line 1988 — Error establishing a database connection

Container Boot Ordering, Bridge DNS & Persistence for WordPress / MariaDB + Redis

Running WordPress in Docker Compose paired with MariaDB 11, Redis 7 object caching, and Nginx delivers dramatic performance gains over shared hosting; but naive Compose setups frequently greet visitors with "Error establishing a database connection" on cold starts. MariaDB 11 needs 10 to 20 seconds to bootstrap its InnoDB tablespace and initial user grants before accepting PHP connections.

Unlike older MySQL tutorials that rely on custom shell scripts or mysqladmin, official MariaDB 11 Docker images ship with a purpose-built healthcheck.sh binary supporting --connect and --innodb_initialized flags. Combining that native probe with redis-cli ping and condition: service_healthy guarantees WordPress and Nginx only start once both MariaDB InnoDB and Redis are genuinely ready.

Separating Nginx and WordPress PHP-FPM into distinct containers lets Nginx handle static uploads, WebP images, Gzip compression, and client_max_body_size limits (important for theme/plugin ZIP uploads) without waking PHP workers. Meanwhile, Redis 7 powers persistent WordPress object caching (via the Redis Object Cache plugin), slashing repeated wp_options and postmeta SQL queries by over 80%.

For security on a Linux VPS, keep MariaDB (3306) and Redis (6379) strictly internal using expose: on app_network instead of publishing host ports to 0.0.0.0, and mount both wp-content uploads and MariaDB data onto named Docker volumes so container upgrades never erase media libraries or blog posts.

Finally, configure WP_REDIS_HOST=redis and WORDPRESS_DB_HOST=mariadb:3306 in your .env file, never localhost, and verify Nginx fastcgi_pass or proxy_pass uses resolver 127.0.0.11 so rebuilding the WordPress container never causes 502 errors.

Before migrating live WordPress traffic onto Docker Compose, test a full container stop-and-recreate cycle (docker compose down && docker compose up -d) to verify that MariaDB tables, uploaded wp-content media, and Redis object cache connections recover automatically without manual intervention. Pairing MariaDB 11's native healthcheck.sh with firewall-safe expose: directives keeps your blog fast, secure, and immune to accidental UFW bypasses.

Step-by-Step WordPress / MariaDB + Redis Docker Compose Setup Guide

Follow each step below to pair the generated Compose file with accurate container DNS variables, safe database migrations, and zero-downtime restarts.

  1. 1Configure WordPress Database and Redis Object Cache Environment Variables

    .env

    Point WordPress directly at Docker Compose service hostnames "mariadb" and "redis" so wp-config.php connects reliably across app_network.

    .envdotenv
    DB_DATABASE=wordpress_db
    DB_USERNAME=wp_user
    DB_PASSWORD=change_me_strong
    DB_ROOT_PASSWORD=root_change_me
    
    WORDPRESS_DB_HOST=mariadb:3306
    WORDPRESS_DB_USER=wp_user
    WORDPRESS_DB_PASSWORD=change_me_strong
    WORDPRESS_DB_NAME=wordpress_db
    WP_REDIS_HOST=redis
    WP_REDIS_PORT=6379
  2. 2Wire Redis Object Cache Constants Into wp-config.php

    wp-config-extra.php

    Define WP_REDIS_HOST and WP_CACHE so the Redis Object Cache plugin routes all transient and query object lookups to your Redis 7 container.

    wp-config-extra.phpphp
    define('WP_CACHE', true);
    define('WP_REDIS_HOST', getenv('WP_REDIS_HOST') ?: 'redis');
    define('WP_REDIS_PORT', 6379);
    define('WP_REDIS_PREFIX', 'wp_prod_');
  3. 3Raise Upload Limits in Both PHP and Nginx for Themes & Media

    php/uploads.ini

    Match PHP upload_max_filesize and post_max_size with Nginx client_max_body_size (e.g., 64M) so WordPress media uploads never trigger 413 Request Entity Too Large.

    php/uploads.iniini
    file_uploads = On
    memory_limit = 256M
    upload_max_filesize = 64M
    post_max_size = 64M
    max_execution_time = 120
  4. 4Launch Stack and Verify MariaDB 11 healthcheck.sh Status

    terminal

    Confirm both mariadb and redis show (healthy) in docker compose ps before opening the WordPress setup wizard.

    terminalbash
    docker compose up -d
    docker compose ps
    docker compose exec redis redis-cli ping

Common WordPress / MariaDB + Redis Docker Compose Pitfalls

Avoid these three container orchestration mistakes before deploying your Compose stack onto staging or production servers.

Pitfall 1

Using mysqladmin Instead of MariaDB 11 Native healthcheck.sh

MariaDB 11 deprecated legacy mysql* symlink names in favor of mariadb-admin and ships its official healthcheck.sh --connect --innodb_initialized script specifically for Docker Compose healthchecks.

Pitfall 2

Forgetting to Persist /var/www/html/wp-content in a Named Volume

Persisting only db_data saves blog post text in MariaDB, but recreating the WordPress container wipes every uploaded image, plugin, and theme unless wp_content is also mounted to a named volume.

Pitfall 3

Mixed-Content Redirect Loops When Terminating HTTPS at Nginx

When Nginx terminates HTTPS and forwards HTTP to WordPress, add $_SERVER["HTTPS"] = "on"; when HTTP_X_FORWARDED_PROTO equals "https" in wp-config.php so wp-admin does not enter an infinite 301 loop.

Related Tools

Pair Your Docker Compose Stack With .env Linting, Nginx TLS & CORS Checks

Validate your .env file for unescaped $$ interpolation or leaked secrets, configure Nginx DNS resolution, and verify cross-origin headers:

Frequently Asked Questions

Why does WordPress show "Error establishing a database connection" right after docker compose up?
MariaDB 11 needs 10–20 seconds to initialize InnoDB on a new volume. Using healthcheck.sh --connect --innodb_initialized with condition: service_healthy holds WordPress until MariaDB is ready.
Does Redis replace Nginx page caching or complement it?
They complement each other: Redis caches database objects (crucial for logged-in WooCommerce or wp-admin users), while Nginx FastCGI caching serves anonymous page views directly from RAM/disk.
Why should MariaDB use expose: ["3306"] instead of ports: ["3306:3306"]?
Publishing 3306:3306 opens MariaDB on 0.0.0.0 via Docker iptables rules, bypassing UFW firewalls. Keeping 3306 internal via expose: ensures only the WordPress container on app_network can reach the database.
How do I back up both WordPress database and uploads cleanly?
Run mariadb-dump inside the mariadb container via docker compose exec -T mariadb mariadb-dump and archive the wp_content volume alongside it on a nightly schedule.
Browse all 10 Compose stacks →