diff --git a/README.md b/README.md index 1080723..f118a2d 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,209 @@ -# webdev +# 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](#prerequisites) +2. [Directory Structure](#directory-structure) +3. [Setup Instructions](#setup-instructions) +4. [Managing Projects](#managing-projects) +5. [Switching PHP Versions](#switching-php-versions) +6. [Using the Build Tools Container](#using-the-build-tools-container) +7. [Using php-spy Profiler](#using-php-spy-profiler) +8. [Troubleshooting](#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 + cd + ``` + +2. Create the necessary directories: + ``` + mkdir -p apache/vhosts projects ssl + ``` + +3. Copy the provided Dockerfiles and configuration files into their respective directories. + +4. Build and start the Docker environment: + ``` + docker-compose up -d + ``` + +5. 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/`: + ```apache + + 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 + + + SetHandler "proxy:fcgi://php74:9074" + + + + + 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 + + + SetHandler "proxy:fcgi://php74:9074" + + + ``` + +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/`: + ```apache + + # 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" + + ``` + +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 +```