Leveraging Docker Swarm and Vault for Secure, Scalable WordPress Headless Deployments

Docker Swarm for WordPress Headless Orchestration

Deploying WordPress in a headless configuration demands a robust orchestration layer capable of managing multiple services, scaling them independently, and ensuring high availability. Docker Swarm provides a native, integrated solution for container orchestration that is often overlooked in favor of more complex alternatives. Its simplicity and tight integration with the Docker ecosystem make it an excellent choice for this use case.

We’ll structure our Swarm deployment around several key services:

• WordPress Frontend (PHP-FPM): The core WordPress application, serving the REST API and potentially a static site generator’s build process.
• Nginx Reverse Proxy: Handles incoming traffic, SSL termination, caching, and routing requests to the appropriate backend services.
• MySQL Database: The persistent data store for WordPress.
• Redis Cache: For object caching to improve performance.
• HashiCorp Vault: For secure management of secrets.

Setting Up the Docker Swarm Cluster

Assuming you have multiple Docker hosts (VMs or bare metal) ready, initializing and joining them to a Swarm is straightforward. On your manager node:

docker swarm init --advertise-addr 

This command will output a `docker swarm join` command. Execute this command on all your worker nodes to add them to the Swarm.

Securing Secrets with HashiCorp Vault

Storing sensitive information like database credentials, API keys, and WordPress salts directly in Docker Compose files or environment variables is a security anti-pattern. HashiCorp Vault is the industry standard for managing secrets. We’ll integrate Vault into our Swarm to dynamically inject secrets into our services.

First, deploy Vault as a Swarm service. For simplicity in this example, we’ll run a single Vault instance. In production, you’d want a highly available setup with multiple Vault replicas and a dedicated storage backend (e.g., Consul, integrated storage).

# On a manager node
docker service create \
  --name vault \
  --hostname vault \
  -p 8200:8200 \
  -v vault-data:/vault/data \
  --mount type=volume,source=vault-data,target=/vault/data \
  vault:latest server -dev -dev-listen-address 0.0.0.0:8200

The -dev flag starts Vault in development mode with a single-node, in-memory storage. This is suitable for testing but not for production. For production, you would configure Vault with a persistent backend and proper sealing/unsealing procedures.

Next, we need to configure Vault to store our WordPress secrets. We’ll use the KV v2 secrets engine.

# After Vault is running, get the dev token
export VAULT_ADDR='http://:8200'
export VAULT_TOKEN='s.xxxxxxxxxxxxxxxxxxxx' # Replace with your actual dev token

# Enable KV v2 secrets engine
vault secrets enable -path=wordpress kv-v2

# Write WordPress database credentials
vault kv put wordpress/db \
  username=wp_user \
  password=$(openssl rand -base64 16) \
  database=wordpress_db

# Write WordPress salts (generate from https://api.wordpress.org/secret-key/1.1/salt/)
vault kv put wordpress/config \
  AUTH_KEY='...' \
  SECURE_AUTH_KEY='...' \
  LOGGED_IN_KEY='...' \
  SECURE_LOGGED_IN_KEY='...' \
  NONCE_KEY='...' \
  AUTH_SALT='...' \
  SECURE_AUTH_SALT='...' \
  LOGGED_IN_SALT='...' \
  NONCE_SALT='...'

Docker Compose for Swarm Deployment

We’ll define our services using a docker-compose.yml file. This file will be deployed to the Swarm using docker stack deploy.

version: '3.7'

services:
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro # For SSL certificates
    deploy:
      replicas: 2
      restart_policy:
        condition: on-failure
      update_config:
        parallelism: 1
        delay: 10s
    networks:
      - app-network

  wordpress:
    image: wordpress:latest
    environment:
      # These will be injected by Vault via a sidecar or init container in a more advanced setup.
      # For simplicity here, we'll assume they are pre-populated or managed externally.
      # In a real-world scenario, use a Vault agent or CSI driver.
      WORDPRESS_DB_HOST: mysql
      WORDPRESS_DB_USER: ${DB_USER} # Placeholder for Vault injection
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD} # Placeholder for Vault injection
      WORDPRESS_DB_NAME: wordpress_db
      # WordPress salts will also be injected similarly
    volumes:
      - wordpress-data:/var/www/html
    depends_on:
      - mysql
    networks:
      - app-network
    deploy:
      replicas: 3
      restart_policy:
        condition: on-failure
      update_config:
        parallelism: 1
        delay: 10s

  mysql:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD} # Placeholder for Vault injection
      MYSQL_DATABASE: wordpress_db
      MYSQL_USER: ${DB_USER} # Placeholder for Vault injection
      MYSQL_PASSWORD: ${DB_PASSWORD} # Placeholder for Vault injection
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - app-network
    deploy:
      replicas: 1 # Typically one primary DB instance, consider replication for HA
      restart_policy:
        condition: on-failure

  redis:
    image: redis:alpine
    networks:
      - app-network
    deploy:
      replicas: 2
      restart_policy:
        condition: on-failure

volumes:
  wordpress-data:
  mysql-data:

networks:
  app-network:
    driver: overlay
    attachable: true

Note on Vault Integration: The above docker-compose.yml uses environment variable placeholders like ${DB_USER}. In a production Swarm, you would integrate Vault more deeply. Common methods include:

• Vault Agent Sidecar: Run a Vault agent as a sidecar container alongside your WordPress application. The agent can authenticate with Vault (e.g., using its Swarm token or a Kubernetes service account if using K8s) and periodically fetch secrets, writing them to a shared volume or injecting them as environment variables.
• Vault CSI Driver (Kubernetes): If you were using Kubernetes, the CSI driver is the preferred method.
• Custom Init Container: An init container that runs before the main application container, fetches secrets from Vault, and makes them available (e.g., as files in a shared volume).

For this example, we’ll simulate Vault injection by pre-populating the environment variables on the Docker hosts or using a mechanism to pass them during stack deployment. A more secure approach would involve the Vault agent.

Nginx Configuration for Headless WordPress

The Nginx configuration is crucial for routing traffic and serving static assets. For a headless setup, Nginx will primarily act as a reverse proxy to the WordPress PHP-FPM service and potentially serve cached API responses or static files generated by a build process.

# nginx.conf
daemon off;
worker_processes auto;

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/json; # Default to JSON for API responses

    sendfile        on;
    keepalive_timeout  65;

    # Gzip compression for API responses
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types application/json text/plain text/css application/javascript application/x-javascript application/xml application/x-shockwave-flash application/vnd.ms-fontobject font/opentype;

    # Define upstream for WordPress PHP-FPM
    upstream wordpress_backend {
        # Use DNS round-robin for service discovery in Swarm
        server wordpress:9000;
    }

    server {
        listen 80;
        server_name your-domain.com; # Replace with your domain

        # Serve static assets directly if any
        # location /static/ {
        #     alias /var/www/html/static/;
        #     expires 30d;
        # }

        location / {
            proxy_pass http://wordpress_backend;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;

            # Cache API responses for a short duration
            proxy_cache STATIC;
            proxy_cache_valid 200 302 1m; # Cache for 1 minute
            proxy_cache_key "$scheme$request_method$host$request_uri";
            add_header X-Proxy-Cache $upstream_cache_status;
        }

        # Optional: Handle WordPress REST API specifically if needed
        # location /wp-json/ {
        #     proxy_pass http://wordpress_backend;
        #     proxy_set_header Host $host;
        #     proxy_set_header X-Real-IP $remote_addr;
        #     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        #     proxy_set_header X-Forwarded-Proto $scheme;
        # }

        # Add SSL configuration here for port 443
    }

    # Add SSL server block for port 443
    server {
        listen 443 ssl http2;
        server_name your-domain.com; # Replace with your domain

        ssl_certificate /etc/nginx/certs/fullchain.pem; # Path to your SSL certificate
        ssl_certificate_key /etc/nginx/certs/privkey.pem; # Path to your SSL private key

        # Include SSL best practices (e.g., from Mozilla SSL Config Generator)
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_prefer_server_ciphers on;
        ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
        ssl_session_cache shared:SSL:10m;
        ssl_session_timeout 10m;
        ssl_session_tickets off;

        location / {
            proxy_pass http://wordpress_backend;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;

            proxy_cache STATIC;
            proxy_cache_valid 200 302 1m;
            proxy_cache_key "$scheme$request_method$host$request_uri";
            add_header X-Proxy-Cache $upstream_cache_status;
        }
    }
}

To use this configuration, you’ll need to create a nginx.conf file on your Docker host and mount it into the Nginx container. You’ll also need to place your SSL certificates (fullchain.pem and privkey.pem) in a certs directory.

Deploying the Stack

Once your docker-compose.yml and nginx.conf are ready, and your Vault secrets are populated, you can deploy the stack to your Swarm.

# On a manager node
# Ensure you have the necessary environment variables set for Vault secrets
# e.g., export DB_USER=$(vault kv get -field=username wordpress/db | tail -n 1)
# This manual step is a simplification. A Vault agent or similar would automate this.

# For demonstration, let's assume you've manually retrieved and set these:
export DB_USER="wp_user"
export DB_PASSWORD=$(openssl rand -base64 16) # Should match Vault value
export MYSQL_ROOT_PASSWORD=$(openssl rand -base64 32) # Should match Vault value

# Deploy the stack
docker stack deploy -c docker-compose.yml wordpress_stack

This command will create all the defined services, networks, and volumes across your Swarm cluster. Docker Swarm will handle scheduling containers onto available nodes, ensuring the desired number of replicas are running.

Monitoring and Management

Managing a Swarm stack involves several key commands:

• docker stack services wordpress_stack: List services in the stack.
• docker service ps wordpress_stack_wordpress: View the status of individual tasks (containers) for a service.
• docker service logs wordpress_stack_wordpress: View logs for a service.
• docker service scale wordpress_stack_wordpress=5: Scale the WordPress service to 5 replicas.
• docker service update --image wordpress:latest wordpress_stack_wordpress: Update the WordPress image.
• docker node ls: List nodes in the Swarm.

For more advanced monitoring, consider integrating with Prometheus and Grafana. Docker’s built-in metrics endpoints can be scraped by Prometheus, and Grafana can visualize this data.

Advanced Considerations and Next Steps

This setup provides a solid foundation. For production-grade deployments, consider:

• Database High Availability: Implement MySQL replication or use a managed database service.
• Vault HA: Deploy Vault in a highly available configuration with a persistent backend.
• Automated Secret Injection: Utilize Vault Agent or a similar mechanism for secure, dynamic secret injection into application containers.
• CI/CD Integration: Automate the build, test, and deployment process using tools like GitLab CI, GitHub Actions, or Jenkins.
• Health Checks: Implement robust health checks in your Docker Compose files for better service management.
• Persistent Storage: For production, use more robust storage solutions than Docker volumes, such as NFS, Ceph, or cloud provider block storage, especially for the database.
• CDN Integration: Offload static asset delivery and caching to a Content Delivery Network.
• WordPress Optimization: Fine-tune WordPress settings, use caching plugins (if applicable to your headless strategy), and optimize database queries.