DockForge - Docker Development Environment

A reusable Docker development environment for PHP web applications with Apache, MySQL, Redis, and additional development tools.

🚀 Features

• Multi-stage Docker builds with optimized configurations for different environments
• PHP 8.4 with Apache and SSL support
• MySQL 9.3 database server
• Redis for caching and session storage
• Mailpit for email testing during development
• phpRedisAdmin for Redis management
• Environment-specific configurations (local, test, production)
• Hot-reload development with volume mounting
• XDebug integration for PHP debugging

📁 Project Structure

.docker/
├── .env                    # Environment variables
├── .gitignore             # Git ignore rules
├── docker-compose.yml     # Main Docker Compose configuration
├── bin/
│   └── start             # Environment startup script
└── website/
    ├── Dockerfile        # Multi-stage PHP application Dockerfile
    └── default-ssl.conf  # Apache SSL virtual host configuration

🛠 Quick Start

Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+

Setup

1. Copy the .docker folder to your project root:

   cp -r .docker /path/to/your/project/
   cd /path/to/your/project/.docker

2. Configure environment variables:

   cp .env.example .env  # If you have an example file
   # Or edit .env directly with your project-specific values

3. Create required directories:

   mkdir -p ../.storage/mysql_server
   mkdir -p ../.storage/redis_server

4. Start the environment:

   chmod +x bin/start
   ./bin/start local

🔧 Configuration

Environment Variables (.env)

Variable	Description	Default
WEBSITE_UI_PORT	Port for web application	8080
WEBSITE_ENVIRONMENT	Build target (local/test/production)	local
MYSQL_DEFAULT_DATABASE	MySQL database name	app
MYSQL_ROOT_PASSWORD	MySQL root password	secret
MYSQL_USER	MySQL application user	app
MYSQL_PASSWORD	MySQL application password	secret
MAILPIT_WEB_UI_PORT	Mailpit web interface port	8025
PHPREDISADMIN_WEB_UI_PORT	phpRedisAdmin port	7379

Docker Services

🌐 Website (PHP Application)

• Image: Custom multi-stage build
• Port: Configured via WEBSITE_UI_PORT (default: 8080)
• Features: PHP 8.4, Apache, SSL, XDebug (local), Node.js
• Volume: ../website:/var/www/html (development mode)

🗄 MySQL Server

• Image: mysql:9.3
• Port: 3306 (internal)
• Storage: Persistent volume at ../.storage/mysql_server

🔴 Redis Server

• Image: redis:latest
• Port: 6379 (internal)
• Storage: Persistent volume at ../.storage/redis_server

📧 Mailpit (Email Testing)

• Image: axllent/mailpit
• Port: Configured via MAILPIT_WEB_UI_PORT (default: 8025)
• Purpose: Capture and view emails during development

🔧 phpRedisAdmin

• Image: actency/docker-phpredisadmin
• Port: Configured via PHPREDISADMIN_WEB_UI_PORT (default: 7379)
• Purpose: Redis database management interface

🏗 Docker Build Stages

The Dockerfile includes multiple stages optimized for different use cases:

Base Stage

• PHP 8.4 with Apache
• Essential PHP extensions (PDO, MySQL, Redis, GD, etc.)
• Composer installation
• SSL certificate generation

Build Stage

• Adds OPcache for production optimization
• Inherits from base stage

Production Stage

• Optimized for production deployment
• Includes Node.js for asset compilation
• No development tools

Test Stage

• Extends production stage
• Includes XDebug with coverage mode
• Ideal for CI/CD testing

Local Stage

• Development-optimized configuration
• XDebug with debug mode
• OPcache disabled for immediate code changes
• VSCode debugging support

Queue Worker Stage

• Background job processing
• Runs Laravel queue workers
• Minimal footprint

Scheduler Stage

• Cron job replacement
• Runs Laravel scheduler
• Handles scheduled tasks

🚀 Usage Examples

Starting Different Environments

# Local development (default)
./bin/start local

# Testing environment
./bin/start test

# Production environment
./bin/start production

Accessing Services

• Web Application: https://localhost:8080 (or your configured port)
• Mailpit: http://localhost:8025
• phpRedisAdmin: http://localhost:7379
• MySQL: localhost:3306 (from host)
• Redis: localhost:6379 (from host)

Common Docker Commands

# View running containers
docker-compose ps

# View logs
docker-compose logs -f website

# Access container shell
docker-compose exec website bash

# Stop all services
docker-compose down

# Rebuild and start
docker-compose up --build -d

🔄 Adapting for Your Project

1. Update Directory Structure

Ensure your project has the following structure:

your-project/
├── .docker/          # This Docker configuration
├── website/          # Your web application code
│   └── public/       # Web server document root
└── .storage/         # Persistent data storage
    ├── mysql_server/
    └── redis_server/

2. Customize Environment Variables

Edit .docker/.env to match your project requirements:

• Update database credentials
• Change port numbers if needed
• Modify application environment

3. Modify Dockerfile (if needed)

The Dockerfile is designed for PHP applications but can be customized:

• Add additional PHP extensions
• Include project-specific dependencies
• Modify Apache configuration

4. Update Apache Configuration

Edit .docker/website/default-ssl.conf:

• Change document root if needed
• Add custom virtual host settings
• Modify SSL configuration

🔍 Debugging

XDebug Configuration

For local development, XDebug is configured to work with VSCode:

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal

VSCode Launch Configuration

Add to your .vscode/launch.json:

{
    "name": "Listen for XDebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "pathMappings": {
        "/var/www/html": "${workspaceFolder}/website"
    }
}

📝 Best Practices

1. Environment Isolation: Always use environment-specific configurations
2. Data Persistence: Use named volumes for database storage
3. Security: Never commit .env files with production credentials
4. Performance: Use production stage for deployment
5. Development: Use local stage with volume mounting for development

🔧 Troubleshooting

Common Issues

1. Port conflicts: Change ports in .env if already in use
2. Permission issues: Ensure Docker has access to project directories
3. SSL warnings: Accept self-signed certificate for local development
4. Database connection: Verify MySQL service is running and credentials are correct

Logs and Monitoring

# Check all service logs
docker-compose logs

# Monitor specific service
docker-compose logs -f mysql_server

# Check container health
docker-compose ps

📄 License

This Docker configuration is designed to be reusable across multiple projects. Feel free to modify and adapt according to your needs.

---

🤝 Contributing

When adapting this configuration for new projects:

1. Test the setup thoroughly
2. Document any project-specific modifications
3. Update environment variables appropriately
4. Ensure security best practices are followed

For questions or improvements, please refer to the project documentation or create an issue.