Generate config.php with Docker Compose: Step-by-Step Guide (2026)

Containerizing a legacy PHP application can significantly simplify its deployment and scaling. However, handling configurations dynamically during the build process, such as generating a config.php file, can pose challenges. This tutorial will guide you through creating a config.php file during Docker Compose build time using environment variables, eliminating the need for manual configuration post-deployment.

Key Takeaways

• Learn to generate config.php using Docker Compose.
• Understand how to use environment variables for configuration.
• Automate PHP configuration file creation during build time.
• Improve deployment efficiency for legacy PHP applications.

Introduction

Legacy PHP applications often rely on static configuration files like config.php for database connections and other settings. In a containerized environment, dynamically generating this file from environment variables can enhance flexibility and portability. This approach also aligns with the twelve-factor app methodology, promoting environment-agnostic configurations.

This tutorial will take you through a step-by-step process to configure a Docker Compose setup that automatically generates a config.php file using environment variables. This method will streamline your deployment process, removing the need for manual configuration adjustments across different environments.

Prerequisites

• Basic understanding of Docker and Docker Compose.
• Familiarity with PHP and configuration files.
• Docker and Docker Compose installed on your development machine (latest versions as of 2026).
• A legacy PHP application that requires a config.php file.

Step 1: Set Up Your Docker Environment

First, ensure that Docker and Docker Compose are installed on your system. You can verify this by running:

docker --version
docker-compose --version

If not installed, follow the official documentation for your operating system to set them up.

Step 2: Prepare Your Dockerfile

Create a Dockerfile in the root directory of your PHP application. This file will define the environment in which your application runs.

FROM php:8.1-apache
COPY . /var/www/html
RUN docker-php-ext-install mysqli

The Dockerfile above uses the official PHP Docker image with Apache and installs the mysqli extension for database connectivity.

Step 3: Define Your Docker Compose File

Create a docker-compose.yml file to manage multi-container applications with Docker Compose:

version: '3.8'
services:
  web:
    build: .
    ports:
      - "80:80"
    environment:
      DB_HOST: db
      DB_USER: exampleuser
      DB_PASSWORD: examplepass
      DB_NAME: exampledb
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: exampledb
      MYSQL_USER: exampleuser
      MYSQL_PASSWORD: examplepass
    volumes:
      - db_data:/var/lib/mysql
volumes:
  db_data:

This configuration sets up two services: a web server running PHP and a MySQL database. Environment variables are used for database configurations.

Step 4: Create a Script to Generate config.php

Create a PHP script named generate_config.php that reads environment variables and writes them to config.php:

<?php
$config = <<<EOT
<?php
return [
    'db_host' => getenv('DB_HOST'),
    'db_user' => getenv('DB_USER'),
    'db_password' => getenv('DB_PASSWORD'),
    'db_name' => getenv('DB_NAME'),
];
EOT;
file_put_contents('/var/www/html/include/config.php', $config);

This script will be executed during the build process to populate the config.php file with the correct values.

Step 5: Modify Dockerfile to Execute Script

Update your Dockerfile to execute the generate_config.php script:

FROM php:8.1-apache
COPY . /var/www/html
RUN docker-php-ext-install mysqli
RUN php /var/www/html/generate_config.php

By adding the script execution to the Dockerfile, you ensure that config.php is generated each time the image is built.

Step 6: Build and Run Your Docker Containers

Now, use Docker Compose to build and start your application:

docker-compose up --build

This command will build the Docker images and start the containers, generating the config.php file based on the specified environment variables.

Common Errors/Troubleshooting

• File Permissions: Ensure that your Dockerfile and PHP scripts have the correct file permissions to execute within the container.
• Environment Variables: Double-check that all required environment variables are correctly set in your docker-compose.yml.
• Volume Mounting: If you encounter issues with file persistence, verify that your Docker volumes are correctly configured.

Conclusion

By following these steps, you can automate the generation of a config.php file during the Docker build process, leveraging the power of environment variables to maintain flexibility and consistency across different environments. This approach not only simplifies the deployment of legacy PHP applications but also enhances their portability and scalability within modern infrastructure.

Frequently Asked Questions

Can I use this method for other configuration files?

Yes, this approach can be adapted to generate other types of configuration files by modifying the script to handle different variables and output formats.

What if I have multiple environments?

Use separate Docker Compose files or environment variable files for each environment to manage different configurations seamlessly.

Is this approach secure for production?

Ensure sensitive data in environment variables is managed securely, possibly through Docker Secrets or other secure mechanisms for handling secrets in production.