Debugging a MediaWiki‑MariaDB Docker Compose stack that silently fails due to pl

by

Summary

This postmortem covers a common Docker Compose misconfiguration when deploying MediaWiki against MariaDB. The supplied docker-compose.yml contains placeholder tokens (---) in place of real values for the container name, database password, and other critical fields. While the structure of the compose file is mostly sound, these missing values prevent the stack from starting correctly and highlight broader pitfalls junior engineers encounter when wiring together official images.

Key takeaway: A compose file that looks structurally correct but contains unresolved placeholders will fail silently or with cryptic errors, leading teams to chase network or permission issues instead of fixing the config itself.

Root Cause

The root cause is that the YAML configuration was written with redacted or placeholder values still in place. Specifically:

  • container_name: --- is not a valid container name
  • MYSQL_PASSWORD: --- provides no real password, so the MariaDB container cannot accept incoming connections from MediaWiki
  • ports: - 8080:80 maps correctly but is irrelevant if the app container never starts
  • Volumes are declared but the MediaWiki container has no way to initialize its database schema without valid credentials

When you run docker compose up -d, Docker will start the containers but MediaWiki’s web installer or background initialization will fail to connect to the database, resulting in a non-functional stack.

Why this configuration fails at runtime:

  • MediaWiki attempts to connect to MariaDB using the credentials in LocalSettings.php (or the installer prompt)
  • MariaDB rejects the connection because the password is literally ---
  • MediaWiki shows a database connection error or hangs on the installer
  • The container stays running but the service is completely non-functional

Why This Happens in Real Systems

This pattern of placeholder-driven configs shows up in real environments for several reasons:

  • Copy-paste from documentation or templates where sensitive fields were stubbed out
  • Interview or certification environments where the candidate is expected to recall values from memory
  • Configuration drift in version-controlled files where secrets were removed and never replaced
  • Insufficient pre-flight checks — no one validated the compose file before committing it

Common real-world examples:

  • DevOps engineers committing .env files with PASSWORD=PLACEHOLDER to a shared repo
  • Kubernetes manifests with image: myapp:--- that build pipelines skip because the image doesn’t exist
  • CI/CD pipelines that “succeed” because containers start but services inside them fail to bind

Real-World Impact

The impact of shipping a compose file with unresolved placeholders is significant:

  • Deployment appears successful but the application is broken — this is the worst kind of failure because alerts don’t fire and users see a blank page or error screen
  • Debugging time explodes — engineers spend hours checking network connectivity, volume mounts, and port mappings when the real problem is a missing password
  • Trust in the deployment pipeline erodes — teams start assuming every deploy is broken until proven otherwise
  • Compliance flags — an auditor sees a placeholder password in a config file and flags it as a credential management failure

Specific symptoms you’ll see:

  • Container status shows Up but no HTTP response or a connection refused error
  • MediaWiki installer page never progresses past the database step
  • MariaDB logs show authentication failures
  • Logs contain messages like Access denied for user 'testc'@'%' (using password: YES)

Example or Code

version: '3.8'

services:
  wiki:
    image: mediawiki
    container_name: wiki_container
    restart: always
    ports:
      - "8080:80"
    volumes:
      - images:/var/www/html/images
    depends_on:
      - mariadb

  mariadb:
    image: mariadb
    container_name: mariadb_container
    restart: always
    environment:
      MYSQL_DATABASE: testdb
      MYSQL_USER: testc
      MYSQL_PASSWORD: changeme_secure_password_123
      MYSQL_RANDOM_ROOT_PASSWORD: 'yes'
    volumes:
      - db:/var/lib/mysql

volumes:
  images:
  db:
# Validate before you deploy
docker compose config

# Start the stack
docker compose up -d

# Check container health
docker compose ps

# Inspect the MariaDB logs
docker compose logs mariadb

How Senior Engineers Fix It

Senior engineers treat this issue at multiple layers:

  • Never commit placeholder values. Use .env files or a secrets manager so that local dev and CI/CD inject real values at runtime.
  • Validate configs early. Run docker compose config to catch syntax and placeholder issues before starting containers.
  • Add a smoke test step in CI. After containers start, make an HTTP request or run a DB connection check. Fail the pipeline if the app isn’t responding.
  • Separate config from code. The compose file defines structure; actual secrets come from environment variables or a vault.

A senior engineer’s checklist for this specific stack:

  • container_name is a valid string (lowercase, no special chars)
  • MYSQL_PASSWORD is a real, non-empty password
  • MediaWiki’s DBPassword in LocalSettings.php matches the MYSQL_PASSWORD
  • depends_on ensures MariaDB is ready before MediaWiki tries to connect
  • Volume declarations are consistent and the named volume exists

Why Juniors Miss It

Juniors miss this issue because:

  • They focus on structure over substance. The YAML looks correct — services are defined, ports are mapped, volumes are declared — so they assume it works.
  • They don’t know to run docker compose config. This command surfaces placeholder values and syntax errors before containers even start.
  • They conflate “container is running” with “service is working.” A container can be Up while the application inside it is completely broken.
  • They haven’t been burned yet by silent failures. Once you’ve deployed a broken stack to production because a placeholder password made it through, you never forget to validate credentials again.
  • They treat official images as magic. Prebuilt images handle their own initialization, so juniors assume nothing can go wrong if the compose file “looks right.”

The real lesson: In infrastructure-as-code, a file that parses correctly is not the same as a file that runs correctly. Always validate with docker compose config and add a post-deploy health check.

Leave a Comment