Developer Tools & Environments ADVANCED Linux / macOS / Windows ⏱️ 4 min read πŸ“… Updated: 16 Oct 2026

Containerizing Legacy Apps: Docker Compose Guide for PHP/Python Migration

Learn to modernize deployment of older web applications (PHP or Python) by wrapping them in standardized, portable containers using Docker and Docker Compose.

Gurveer Singh
Gurveer Singh βœ“ Verified Specialist
Founder & Chief Architect Β· hSECURITIES Labs
⚑ FAST-TRACK PROTOCOL

Direct Diagnostic & Remediation Summary

  • 1. Directory Setup: Create a project directory containing your application code, a Dockerfile, and a docker-compose.yml file.
  • 2. Build & Run: Execute the primary orchestration command in the terminal to build images and start all services simultaneously: docker compose up -d --build.
πŸ› οΈ Tools & Prerequisites: Docker Engine installed (Docker Desktop or Docker CE) on Linux/macOS/Windows, basic understanding of Docker concepts, and root/administrator privileges.
STEP 1

Project Structure Initialization & Dependency Mapping

Before containerizing, you must understand the dependencies. Legacy apps often rely on specific versions of PHP extensions or Python libraries that are difficult to manage manually. This step sets up a clean project skeleton.

1. Create Project Directory: Establish a dedicated folder for your application source code and configuration files.

mkdir legacy_app_container
cd legacy_app_container

2. Create Application Subdirectory: Place your existing PHP or Python code base inside this folder.

mkdir app

3. Define Service Requirements: Determine which services are needed (e.g., web server, database). For a standard setup, you need at least the application container and potentially a database container.

  • Check your existing requirements: Is it PHP 7.4? Python 3.8? MySQL 5.7?
  • Note down these versions; they will dictate your base images in Dockerfile/docker-compose.yml.
STEP 2

Dockerfile Creation (The Application Blueprint)

A Dockerfile tells Docker exactly how to build an isolated environment for your application. We will create one tailored to the language.

For PHP Applications:

  1. Create a file named Dockerfile in the root directory (or next to your app code).
  2. Use a base image that matches your required PHP version, and install necessary extensions.
FROM php:7.4-apache  # Example for PHP 7.4 with Apache built-in

For Python Applications:

  1. Create a file named Dockerfile.
  2. Use the appropriate base image and copy dependency files (like requirements.txt).
FROM python:3.8-slim  # Example for Python 3.8 slim build

Adding Code & Dependencies:

  • Copy dependencies: COPY requirements.txt /app/ (Python) or COPY index.php /var/www/html/index.php (PHP).
  • Install Python dependencies: Add a RUN pip install -r requirements.txt command.
  • Expose ports and set the entry point (e.g., WORKDIR /app followed by CMD ["apache2-foreground"] or CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]).
STEP 3

Docker Compose Orchestration (The Ecosystem Manager)

While the Dockerfile builds one service, docker-compose.yml manages the entire stackβ€”the web server, database, and cache together.

Create a file named docker-compose.yml in the root directory:

version: '3.8'
services:
  web:
    build: ./app  # Points to the directory containing your Dockerfile
    ports:
      - "80:80"   # Host_Port:Container_Port
    depends_on:
      - db
    environment:
      DATABASE_URL: ${DB_HOST}:${DB_PORT}
  db:
    image: mysql:5.7 # Use specific, tested versions!
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: legacy_data
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

Crucial Step: Update the version, image tags (e.g., mysql:5.7), and environment variables to perfectly match your legacy application's requirements.

FINAL STEP

Verification, Results & Preventative Maintenance

After running the stack, verification ensures that all services communicate correctly and the application functions as expected in the containerized environment. Never skip this step.

  1. Initial Startup: Execute the build command to ensure no syntax errors exist across all defined services.
docker compose up -d --build

The -d runs it in detached (background) mode, and --build forces Docker to rebuild images using the latest Dockerfiles.

Verification Checks:

  • Check Container Status: Verify all services are running without restarting.
  • docker compose ps
    # Expected output: All services (web, db) show 'Up' status.
  • Test Application Endpoint: Access http://localhost/ in your browser. If the application loads correctly and can connect to the database, the containerization was successful.

Preventative Maintenance Tips:

  • Logging: Periodically check logs for runtime errors that weren't visible during startup:docker compose logs -f web
  • Resource Limits: For production, define resource constraints (CPU/Memory) in your docker-compose.yml file to prevent one service from starving others.
Resolution Complete: You have successfully containerized your legacy application stack into reproducible Docker services using Docker Compose. The next step is migrating production traffic gradually, starting with read-only endpoints before switching the primary write connection.
TROUBLESHOOTING

Common Pitfalls & Advanced Troubleshooting

If standard remediation does not immediately resolve the symptoms for Containerizing Legacy Apps: Docker Compose Guide for PHP/Python Migration, review these advanced diagnostic contingencies on Linux / macOS / Windows:

  • Peripheral & Bus Isolation: Detach non-essential USB accessories and external controllers to isolate IRQ and bus contention.
  • Diagnostic Minimal Boot: Restart Linux / macOS / Windows in Safe / Diagnostic Mode to eliminate third-party daemon conflicts.
  • Firmware Integrity: Check that hardware firmware and UEFI/BIOS revisions are updated to the manufacturer baseline.
COMMAND LINE / TERMINAL
docker compose up -d --build

Frequently Asked Questions

What if my app needs a specific PHP extension not available in the base image?

You must modify your Dockerfile by adding <code>RUN apt-get update && apt-get install -y phpX.Y-extensionname</code> before attempting to run your application.

How do I stop and remove the entire stack safely?

Run <code>docker compose down --volumes</code>. The '--volumes' flag ensures that persistent data volumes (like database backups) are also removed, which is critical for clean testing.

My web container keeps restarting. What should I check first?

Check the logs immediately using <code>docker compose logs web</code>. Look for segmentation faults or connection refusal errors; these point to code incompatibility with the new environment variables or base OS libraries.

Engineering Assistance

Need help implementing this solution?

Our cybersecurity and infrastructure engineers can audit, harden, or configure your systems directly.

Request Technical Assistance β†’
Gurveer Singh
Gurveer Singh βœ“ Verified Author
Founder & CEO at hSECURITIES | Cybersecurity Educator | Security Researcher | Ethical Hacking Enthusiast | Technology Mentor
Meet the Founder β†’

Gurveer Singh Saggu is the Founder and CEO of hSECURITIES, a cybersecurity and technology education platform focused on practical learning, digital security awareness, hardware diagnostics, Linux administration, and real-world cybersecurity training.

With a strong passion for technology, ethical hacking, and security education, he has spent years helping students, professionals, and organizations understand modern cyber threats and develop practical technical skills. Through hSECURITIES, he creates hands-on learning resources, technical guides, security awareness content, and community-driven initiatives that make cybersecurity more accessible.

His mission is to bridge the gap between theoretical knowledge and practical implementation by providing step-by-step learning experiences, technical troubleshooting resources, and security-focused educational platforms.

Community Discussion & Confirmations (0)

Technical questions, hardware findings, and verified fix reports.

No reader questions posted yet. Have you tried this solution or experienced an edge case? Post below.

Ask a Question or Share Solution