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:
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.
1Configure WordPress Database and Redis Object Cache Environment Variables
.envPoint WordPress directly at Docker Compose service hostnames "mariadb" and "redis" so wp-config.php connects reliably across app_network.
.envdotenvDB_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=63792Wire Redis Object Cache Constants Into wp-config.php
wp-config-extra.phpDefine 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.phpphpdefine('WP_CACHE', true); define('WP_REDIS_HOST', getenv('WP_REDIS_HOST') ?: 'redis'); define('WP_REDIS_PORT', 6379); define('WP_REDIS_PREFIX', 'wp_prod_');3Raise Upload Limits in Both PHP and Nginx for Themes & Media
php/uploads.iniMatch 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.iniinifile_uploads = On memory_limit = 256M upload_max_filesize = 64M post_max_size = 64M max_execution_time = 1204Launch Stack and Verify MariaDB 11 healthcheck.sh Status
terminalConfirm both mariadb and redis show (healthy) in docker compose ps before opening the WordPress setup wizard.
terminalbashdocker 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.
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.
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.
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.
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:
Fix Docker Compose .env substitution bugs and broken bcrypt hashes. Detect unescaped $ characters, spaces around =, and .env vs env_file differences locally.
Prevent 502 Bad Gateway and Nginx startup crashes in Docker Compose using resolver 127.0.0.11 and variable proxy_pass for dynamic container restarts.
Fix Nginx reverse proxy CORS bugs for Docker APIs. Prevent duplicate Access-Control-Allow-Origin headers, add always on 4xx/5xx errors, and handle OPTIONS 204.
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.
Related Docker Compose Stack Guides
Browse all 10 Compose stacks →Docker Compose Laravel + MySQL 8 + Redis Queue Stack & Healthcheck Guide
Generate a production Docker Compose file for Laravel 11/12 with MySQL 8, Redis 7, and queue:work using mysqladmin and redis-cli service_healthy probes.
Docker Compose FastAPI + PostgreSQL + Nginx VPS Production Stack Guide
Deploy FastAPI, PostgreSQL 16, and Nginx on a Linux VPS with Docker Compose using pg_isready healthchecks, 127.0.0.1 firewall safety, and zero-downtime reloads.
Docker Compose Laravel Octane + PostgreSQL 16 + Reverb WebSockets Guide
Generate a Docker Compose stack for Laravel Octane, PostgreSQL 16, Redis 7, and Laravel Reverb WebSockets with pg_isready healthchecks and firewall safety.
Docker Compose Laravel + PostgreSQL 16 + Meilisearch + Redis Stack Guide
Generate a full-stack Docker Compose setup for Laravel Scout with PostgreSQL 16, Redis 7, and Meilisearch using native healthchecks and persistent volumes.