foundation/documentation/docker-setup.md

Docker Development Environment

This document describes how to set up and use the Docker development environment for the Foundation framework.

Overview

The Docker environment provides:

• PHP 8.1 with Apache web server
• MySQL 8.0 database server
• Xdebug for debugging support
• phpMyAdmin for database management
• Composer for dependency management

Prerequisites

Make sure you have the following installed on your system:

• Docker
• Docker Compose

Services

Application Server (app)

• Port: 8000
• Container: foundation-app
• Base Image: php:8.1-apache
• Features: PHP, Apache, Xdebug, Composer, URL Rewriting

Database Server (db)

• Port: 3306
• Container: foundation-db
• Base Image: mysql:8.0
• Database: foundation
• User: foundation_user
• Password: foundation_password

Database Management (phpmyadmin)

• Port: 8080
• Container: foundation-phpmyadmin
• Base Image: phpmyadmin/phpmyadmin
• Access: http://localhost:8080

Environment Configuration

Docker Environment Variables

The following environment variables are automatically set in the Docker environment:

DB_HOST=db
DB_PORT=3306
DB_DATABASE=foundation
DB_USERNAME=foundation_user
DB_PASSWORD=foundation_password

Xdebug Configuration

PHPStorm Setup

1. Configure PHP Interpreter:

   • Go to Settings > PHP
   • Add new CLI Interpreter: "From Docker, Vagrant..."
   • Select Docker Compose, service: app

2. Configure Debug Settings:

   • Go to Settings > PHP > Debug
   • Set Xdebug port to 9003
   • Check "Can accept external connections"

3. Configure Server:

   • Go to Settings > PHP > Servers
   • Add new server:
     • Name: foundation-docker
     • Host: localhost
     • Port: 8000
     • Debugger: Xdebug
     • Use path mappings: /path/to/local/project → /var/www/html

4. Start Debugging:

   • Set breakpoints in your code
   • Click "Start Listening for PHP Debug Connections"
   • Navigate to http://localhost:8000

VS Code Setup

1. Install PHP Debug Extension

2. Configure launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            }
        }
    ]
}

Common Commands

Container Management

# Start services
docker-compose up -d

# Stop services
docker-compose down

# Restart a service
docker-compose restart app

# View logs
docker-compose logs app

# Access container shell
docker-compose exec app bash

Application Commands

# Install dependencies
docker-compose exec app composer install

# Run tests (when available)
docker-compose exec app vendor/bin/phpunit

# Clear logs
docker-compose exec app rm -f storage/logs/*

# Check PHP version
docker-compose exec app php -v

Database Commands

# Access MySQL CLI
docker-compose exec db mysql -u foundation_user -p foundation

# Import SQL file
docker-compose exec -T db mysql -u foundation_user -pfoundation_password foundation < database/schema.sql

# Export database
docker-compose exec db mysqldump -u foundation_user -pfoundation_password foundation > backup.sql