webdev/README.md

Docker Development Environment Setup

This README provides instructions for setting up and using a Docker-based development environment with Apache, multiple PHP versions, and build tools.

Table of Contents

1. Prerequisites
2. Directory Structure
3. Setup Instructions
4. Managing Projects
5. Switching PHP Versions
6. Using the Build Tools Container
7. Using php-spy Profiler
8. Troubleshooting

Prerequisites

• Docker
• Docker Compose
• Git

Directory Structure

.
├── apache/
│   ├── Dockerfile
│   ├── apache2.conf
│   ├── php-fpm.conf
│   └── vhosts/
├── php/
│   ├── Dockerfile-7.4
│   ├── Dockerfile-8.1
│   ├── Dockerfile-8.3
│   └── Dockerfile-8.4
├── build_tools/
│   └── Dockerfile
├── projects/
├── ssl/
└── docker-compose.yml

Setup Instructions

1. Clone this repository:

   git clone <repository-url>
   cd <repository-directory>
   

2. Build and start the Docker environment:

   docker-compose up -d
   

3. Ensure your local machine's hosts file points *.test to 127.0.0.1.

Managing Projects

Adding a New Project

1. Create a new folder in the ./projects directory:

   mkdir -p ./projects/domainname.test/public_html ./projects/domainname.test/logs
   

2. Add a new virtual host configuration in ./apache/vhosts/:

   <VirtualHost *:80>
       ServerName domainname.test
       DocumentRoot /var/www/domainname.test/public_html
       ErrorLog /var/www/domainname.test/logs/error.log
       CustomLog /var/www/domainname.test/logs/access.log combined
   
       <FilesMatch \.php$>
           SetHandler "proxy:fcgi://php74:9074"
       </FilesMatch>
   </VirtualHost>
   
   <VirtualHost *:443>
       ServerName domainname.test
       DocumentRoot /var/www/domainname.test/public_html
       ErrorLog /var/www/domainname.test/logs/error.log
       CustomLog /var/www/domainname.test/logs/access.log combined
   
       SSLEngine on
       SSLCertificateFile /etc/ssl/private/domainname.test.crt
       SSLCertificateKeyFile /etc/ssl/private/domainname.test.key
   
       <FilesMatch \.php$>
           SetHandler "proxy:fcgi://php74:9074"
       </FilesMatch>
   </VirtualHost>
   

3. Generate a self-signed SSL certificate:

   openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./ssl/domainname.test.key -out ./ssl/domainname.test.crt
   

4. Restart the Apache container:

   docker-compose restart apache
   

Enabling a Project

Ensure the virtual host configuration file is present in ./apache/vhosts/ and restart the Apache container:

docker-compose restart apache

Disabling a Project

1. Rename the virtual host configuration file in ./apache/vhosts/ to add a .disabled extension.
2. Restart the Apache container:

   docker-compose restart apache
   

Removing a Project

1. Remove the project folder from ./projects/.
2. Remove the virtual host configuration file from ./apache/vhosts/.
3. Remove the SSL certificate files from ./ssl/.
4. Restart the Apache container:

   docker-compose restart apache
   

Switching PHP Versions

To switch PHP versions for a specific project:

1. Edit the virtual host configuration file in ./apache/vhosts/:

   <FilesMatch \.php$>
       # Choose the appropriate PHP version:
       # For PHP 7.4 (default):
       SetHandler "proxy:fcgi://php74:9074"
       # For PHP 8.1:
       # SetHandler "proxy:fcgi://php81:9081"
       # For PHP 8.3:
       # SetHandler "proxy:fcgi://php83:9083"
       # For PHP 8.4:
       # SetHandler "proxy:fcgi://php84:9084"
   </FilesMatch>
   

2. Restart the Apache container:

   docker-compose restart apache
   

Using the Build Tools Container

To access the build tools container via SSH:

ssh root@localhost -p 2222

The default password is 'password'. It's recommended to change this in a production environment.

When working with Node.js in the build tools container:

1. First, run: source ~/.nvm/nvm.sh
2. Then you can use Node.js and npm commands as usual.

Using php-spy Profiler

To profile a PHP script using php-spy:

1. Connect to the appropriate PHP container:

   docker-compose exec php74 bash  # or php81, php83, php84
   

2. Run php-spy on a specific PHP process:

   phpspy -p [PID_OF_PHP_PROCESS]
   

   You can find the PID of the PHP process using ps aux | grep php-fpm.

Troubleshooting

• If you encounter permission issues, ensure that your project directories and files have the correct ownership and permissions.
• If a site is not accessible, check that the virtual host configuration is correct and that the Apache container has been restarted.
• For SSL issues, verify that the SSL certificate files are correctly generated and placed in the ./ssl/ directory.
• If PHP processing is not working, ensure that the correct PHP version is specified in the virtual host configuration and that the corresponding PHP-FPM container is running.

For any other issues, check the Docker logs:

docker-compose logs

You can also check individual service logs, e.g.:

docker-compose logs apache
docker-compose logs php74