Separated docs by service

Did another pass over all docs. Clarified/simplified/extended as needed.

README.md

@@ -10,7 +10,7 @@
       —  
     <a href="#common-commands-"><b>Usage</b></a>
     &nbsp;&nbsp;&mdash;&nbsp;&nbsp;
-    <a href="#further-reading"><b>Docs</b></a>
+    <a href="#helpful-info"><b>Docs</b></a>
   </p>
   <br />
 </div>
@@ -20,7 +20,7 @@ __An everyday local development environment for PHP Developers.__ At [Pivotal Ag
 
 ## Intro 👋
 
-This is a set of Docker images to spin up a LAMP stack (Linux, Apache, MySQL and PHP) for developing locally. It's perfect for local development because you can very simply add new sites to specified directory and they're magically accessible as a subdomain of your chosen hostname (eg. `~/Projects/example` maps to `http://example.localhost/`).
+This is a set of Docker images to spin up a LAMP stack (Linux, Apache, MySQL and PHP) for developing locally. It's perfect for local development because you can very simply add new sites to specified folder and they're magically accessible as a subdomain of your chosen hostname (eg. `~/Projects/example` maps to `http://example.localhost/`).
 
 It includes all the required dependencies for everyday PHP development with common tools like Laravel, Wordpress and Magento (1 & 2). Specifically:
 
@@ -101,7 +101,7 @@ cd ~/Projects
 git clone [email protected]:pvtl/docker-dev.git
 cd docker-dev
 ```
-4. Copy `.env.example` to `.env` and set the `DOCUMENTROOT` to your projects folder (eg. `/home/USERNAME/Projects/`)
+4. Copy `.env.example` to `.env` and set the `DOCUMENTROOT` to your projects folder (eg. `~/Projects/`)
 5. Build and start the Docker containers:
 ```
 docker compose up -d
@@ -111,7 +111,7 @@ For ease of use we recommend you also set up the [Daily Shortcuts](https://githu
 
 You can test if your Docker Dev environment is working correctly using a simple PHP info file.
 
-1. Create the folder and file: `/home/USERNAME/Projects/test/index.php`
+1. Create the folder and file: `~/Projects/test/index.php`
 1. Edit the file and paste `<?php phpinfo();`
 1. In your browser, open https://test.localhost. You should see the PHP info page.
 
@@ -143,7 +143,7 @@ docker system prune --volumes
 
 ## Common Commands 🔥
 
-Docker must be running and these commands must be run from the Docker Dev folder (eg. `/home/USERNAME/Projects/docker-dev`).
+Docker must be running and these commands must be run from the Docker Dev folder (eg. `~/Projects/docker-dev`).
 
 Most of these actions can also be done in the Docker Desktop app.
 
@@ -152,7 +152,7 @@ Most of these actions can also be done in the Docker Desktop app.
 | `docker compose start` | Start all containers |
 | `docker compose stop`  | Stop all containers (keeps any config changes you've made to the containers) |
 | `docker compose up -d --build --no-cache` | Recreate all containers from scratch |
-| `docker compose down`  | Tear down all containers (MySQL data and project folders are kept) |
+| `docker compose down --remove-orphans`  | Tear down all containers (MySQL data and project folders are kept) |
 | `docker compose exec php82-fpm zsh`  | Open a zsh terminal in the PHP 8.2 container |
 | `docker compose logs php82-fpm` | View all logs for PHP-FPM 8.2 |
 | `docker compose ps` | Show which containers are running |
@@ -162,7 +162,7 @@ Most of these actions can also be done in the Docker Desktop app.
 
 While the above commands work, they're a bit tedious to type out on a daily basis. You can set up terminal aliases to make life easier.
 
-If you use ZSH, edit `~/.zshrc`. Otherwise edit `~/.bashrc`. Create the file if it doesn't exist.
+If you use ZSH, edit `~/.zshrc`. Otherwise edit `~/.bashrc` (or create the file if it doesn't exist).
 
 1. Paste the code (below) at the bottom of the file. Adjust your folder path to suit.
 1. Close and re-open your terminal to apply the changes
@@ -181,26 +181,14 @@ devin() {
 ```
 
 
-## Further Reading
+## Helpful Info 🤓
 
-- 🚥 [Connections](docs/connections.md)
-    - [Email](docs/connections.md#Email)
-    - [MySQL](docs/connections.md#MySQL)
-    - [Redis](docs/connections.md#Redis)
-    - [Memcached](docs/connections.md#Memcached)
+- [General FAQ's](docs/general-faq.md)
+- [Apache Web Server](docs/apache-web-server.md)
+- [PHP](docs/php.md)
+    - [Blackfire PHP Profiler](docs/blackfire-php-profiler.md)
     - [XDebug](docs/xdebug.md)
-- ❓ [FAQs](docs/faqs.md)
-    - [localhost isn't working](docs/faqs.md)
-    - [Running additional commands inside the container during build](docs/faqs.md#how-do-i-run-additional-commands-inside-the-container-during-build)
-    - [Crons](docs/faqs.md#how-do-i-setuprun-crons)
-    - [BrowserSync](docs/faqs.md#how-do-i-get-browsersync-working-from-inside-a-container)
-    - [CURL requests from/to LDE sites](docs/faqs.md#curl-requests-from-an-lde-site-to-another-lde-site)
-    - [HTTPS](docs/faqs.md#how-do-i-use-httpsssl-for-my-local-containers)
-    - [BlackFire](docs/faqs.md#how-do-i-use-blackfire)
-    - [Mapping a Custom Hostname to a local site](docs/faqs.md#mapping-a-custom-hostname-to-a-local-site)
-    - [Changing your MySQL Root password](docs/faqs.md#changing-your-mysql-root-password)
-    - [Adding custom PHP configuration](docs/faqs.md#adding-custom-php-configuration)
-    - [Using Redis as a session handler](docs/faqs.md#using-redis-as-a-session-handler)
-    - [How do I change the 'default' PHP container?](docs/faqs.md#how-do-i-change-the-default-php-container)
-    - [Custom domains / Testing OAuth Logins](docs/custom-domains.md)
-
+- [MariaDB / MySQL Database](docs/mariadb-database.md)
+- [Mailpit (Email Testing)](docs/mailpit-smtp.md)
+- [Redis](docs/redis.md)
+- [Memcached](docs/memcached.md)

docs/apache-web-server.md

@@ -0,0 +1,43 @@
+# Apache
+
+We use the official [Apache](https://hub.docker.com/_/httpd) image and apply some light customisations on top (ie. enabling modules).
+
+
+## `<folder>.localhost` is not working
+
+Double-check your Docker Dev containers are running.
+
+Most browsers (eg. Google Chrome, Microsoft Edge) will automatically detect the .localhost TLD and connect to your local web server. However, if you are receiving an error it could be because your browser is not doing this.
+
+We recommend manually adding those domains to your [hosts file](docs/general-faq.md#How-can-I-edit-my-hosts-file). eg:
+
+```bash
+127.0.0.1   mysite.php82.pub.localhost
+```
+
+
+## How do I use HTTPS/SSL for my local containers?
+
+HTTPS (port 443) is enabled by default, however Apache is using a self-signed certficate which your browser may reject. You might need to enable a feature flag:
+
+- `edge://flags` or `chrome://flags` or `brave://flags`...
+- Enable: `Allow invalid certificates for resources loaded from localhost.`
+
+
+## Using custom hostnames for local sites
+
+You can set up your Docker Dev environment to handle requests for the real/prod domains. This can be very useful for sites that use OAuth connections, like Google and [Xero](https://www.xero.com/).
+
+Obviously this is only useful for testing OAuth on your local device. It is not suitable for receiving webhooks or sharing the project with others.
+
+1. Browse the `apache/sites/localhost/` or `apache/sites/pub.localhost/` folders and choose a config that matches your needs the best (eg. PHP version, "public" folder)
+2. Copy that config file and save it to `apache/sites/acme-corp.conf`.
+    - NOTE: The folder location and `.conf` file extension is important, but the name itself can be whatever you want.
+4. Edit your new config:
+    1. Edit `ServerName` and type in the actual hostname you want to use. Eg. `ServerName acme-corp.com`
+    2. Delete the `ServerAlias` lines
+    3. Edit the `VirtualDocumentRoot` lines and swap `%1` for your project's folder name (eg. `acme-corp`). You should end up with a fully formed absolute folder path like `VirtualDocumentRoot /var/www/html/acme-corp/public`
+6. Restart Apache: `docker compose restart apache` (run this while inside the docker-dev project folder)
+7. Edit your hosts file and point your domain to 127.0.0.1
+
+_Note that apache will load the conf files in alphabetical order. Because our localhost.conf has a "catch all", any of our custom conf files, must be named alphabetically before localhost.conf_

docs/blackfire-php-profiler.md

@@ -0,0 +1,47 @@
+# Blackfire
+
+Blackfire is a PHP profiler that helps you find bottlenecks in your code. It's a paid service, but you can get a free trial at [blackfire.io](https://blackfire.io).
+
+
+## How does Blackfire work?
+
+Blackfire works by profiling your code as it runs.
+
+A PHP extension must be installed into your PHP container. While the code is running, the PHP extension sends the profiling data to the (local) Blackfire agent container. The agent container processes the data and uploads it to the Blackfire.io website (where you can view the results).
+
+
+## How do I use Blackfire?
+
+By default, Blackfire is commented out (not everyone uses it). To enable:
+
+### Enable Blackfire
+
+1. Edit your `.env` file
+    - Fill in all Blackfire environment variables
+    - Enable the agent container by adding `opt/blackfire.yml` to the `COMPOSE_FILE` list
+1. Enable the Blackfire extension for PHP by uncommenting the `Install Blackfire` lines in `php/xx/Dockerfile` (where "xx" is the version of PHP you're enabling Blackfire for)
+1. Rebuild and restart your containers:
+
+```bash
+docker compose build --pull --no-cache
+docker compose up -d
+```
+
+### Run a profile
+
+1. Sign into [blackfire.io](https://blackfire.io)
+1. Install the Blackfire extension in your browser. Here's one for [Google Chrome](https://chrome.google.com/webstore/detail/blackfire-profiler/miefikpgahefdbcgoiicnmpbeeomffld?utm_source=chrome-ntp-icon)
+1. Navigate to the site/page you'd like to profile
+1. Click the 'Profile' button in the Blackfire browser extension
+
+
+## Troubleshooting common Blackfire issues
+
+1. Check the Blackfire extension is installed in your PHP container. Use `phpinfo()` to confirm.
+1. Check the Blackfire agent (container) is running. Use `docker compose ps` to confirm.
+1. Check your Blackfire environment variables are correct in `.env`.
+
+
+## How do I interpret the results?
+
+The [Blackfire documentation](https://blackfire.io/docs/) should have the answers you are looking for.