Building a Drupal environment with Docker Compose: A complete guide

🚀 Introduction. Drupal is a powerful open source CMS, but configuring a local development environment is a cumbersome task. With Docker Compose, you can configure your web server, database, and PHP environment all at once with one configuration file. In this guide, we’ll walk you through a detailed configuration based on Drupal 10.

—.

📦 Pre-requisites **Preparation

• Install Docker & Docker Compose

  # Verify installation
  docker --version && docker-compose --version

• Create a working directory

  mkdir drupal-docker && cd drupal-docker

—]

🛠 Create a Docker Compose file.

Create a docker-compose.yml file and add the following content to it.

version: '3.8'

services:
  # Database service (MySQL)
  db:
    image: mysql:8.0
    container_name: drupal_db
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: drupal
      MYSQL_USER: drupal
      MYSQL_PASSWORD: drupalpass
    volumes:
      - db_data:/var/lib/mysql
    networks:
      - drupal-network

  # Drupal service (Apache + PHP)
  drupal:
    image: drupal:10-apache
    container_name: drupal_app
    depends_on:
      - db
    ports:
      - "8080:80" # host 8080 → container 80 port
    volumes:
      - drupal_modules:/var/www/html/modules
      - drupal_profiles:/var/www/html/profiles
      - drupal_themes:/var/www/html/themes
      - drupal_sites:/var/www/html/sites
    environment:
      DRUPAL_DATABASE_HOST: db
      DRUPAL_DATABASE_NAME: drupal
      DRUPAL_DATABASE_USER: drupal
      DRUPAL_DATABASE_PASSWORD: drupalpass
    networks:
      - drupal-network

# Define network & volumes
volumes:
  db_data:
  drupal_modules:
  drupal_profiles:
  drupal_themes:
  drupal_sites:

networks:
  drupal-network:
    driver: bridge

—.

🔍 Description of the service configuration.

1. MySQL Service (db)

   • Use the official MySQL 8.0 image
   • Automate DB initialization with environment variables
   • Permanently store data in db_data volume 💾

2. Drupal Service (drupal) Β

   • Use the official Drupal 10+ Apache image
   • Start DB with depends_on and run Drupal afterwards
   • Store site data separately in 4 volumes
     • modules,themes`: manage extensions
     • sites: configuration files and uploads

3. **Network

   • Optimize communication between services with drupal-network

—.

⚙️ Run the Drupal installation

1. Run the container

   docker-compose up -d

   

2. Access the web installation wizard Open http://localhost:8080 in your browser → Enter the Drupal installation screen

3. enter DB information

   • Database type: mysql
   • Host: db (Docker service name)
   • Database name/user/password: Enter the values you defined in docker-compose.yml

—.

🎯 Additional Configuration Tips 1.

1. Change the port

Change the host port to 8000:

ports:
  - "8000:80"

2. Customize PHP settings

Mount the php.ini file:

volumes:
  - ./php.ini:/usr/local/etc/php/conf.d/custom.ini

3. Install Drush (Drupal CLI)

Add Drush to the drupal service:

drupal:
  # ... existing settings ...
  command: >
    bash -c "apt-get update &&
    apt-get install -y drush &&
    apache2-foreground"

—]

⚠️ Troubleshooting

• When DB connection fails Check for errors with docker-compose logs db → Check environment variables for case misspelling
• Permission errors Adjust permissions inside the Drupal container:

  docker exec -it drupal_app chown -R www-data:www-data /var/www/html

—]

✅ **Conclusion

Once you configure your Drupal environment with Docker Compose:

• ⏱️ Build a local environment in less than 5 minutes.
• **🔁 Ensure development/test/production environment consistency with the same configuration
• **🔄 Easier to upgrade/downgrade versions

> 💡 **When applying to a real project > Separate production environment settings with docker-compose.prod.yml file, > Traefik integration to automate HTTPS is recommended.

Final structure:

drupal-docker/
├── docker-compose.yml
├── php.ini (optional)
└── sites/ (mount point)

🌈 Now you can start your journey into the world of Drupal with a single line of docker-compose up -d! D