Merge pull request #305 from boxuk/BWP-120

[BWP-120] Docs Updates

Author: James Amner

docs/skeleton/https.md

@@ -6,56 +6,6 @@ The issue with self-signed certificates is browsers (quite rightly) deem them un
 
 ## Using a local certificate authority (CA)
 
-[The general recommended approach for not relying on self-signed certificates is to set up a local CA](https://web.dev/how-to-use-local-https/). There are several tools for doing this, but perhaps the easiest is [mkcert](https://github.com/FiloSottile/mkcert).
+You should not use a local certificate authority to have a signed certificate that is validated. A local CA will contaminate your trusted CAs. This means, if your local environment is compromised, or mkcert, then your entire HTTPS trust chain can easily be compromised too. It is for this reason we do not set this up by default and cannot recommend this approach.
 
-Before some basic instructions for setting this up, here is some information/disclaimer:
-
-**Installing a local CA is at your own risk. Although it will only be trusted by you, a local CA will contaminate your trusted CAs. This means, if your local environment is compromised, or mkcert, then your entire HTTPS trust chain can easily be compromised too. It is for this reason we do not set this up by default and cannot recommend this approach.**
-
-If you're comfortable with all that and still want to go ahead, here's how you can do it with mkcert.
-
-### Install mkcert
-
-On Mac:
-```bash
-brew install mkcert
-brew install nss # if you use Firefox
-```
-
-For other platforms see: https://github.com/FiloSottile/mkcert#installation
-
-### Add mkcert to your local root CAs
-
-```bash
-mkcert -install
-```
-
-### Generate a certificate
-
-```bash
-mkcert my-project.local -cert-file docker/nginx/local_https_cert.pem -key-file docker/nginx/local_https_key.pem # Change the host accordingly
-```
-
-### Update docker config
-
-Add the following volumes to the `nginx` container within `docker-compose.yml`
-
-```yaml
-- './docker/nginx/local_https_cert.pem:/etc/pki/tls/certs/local_https_cert.pem:delegated'
-- './docker/nginx/local_https_key.key:/etc/pki/tls/private/local_https_key.key:delegated'
-```
-
-Update `docker/nginx/conf/app.conf` to point to your certificate and key:
-
-```ini
-ssl_certificate /etc/pki/tls/certs/local_https_cert.pem;
-ssl_certificate_key /etc/pki/tls/local_https_key.pem;
-```
-
-### Rebuild containers
-
-`docker-compose stop; docker-compose build; docker-compose up`
-
-## Any other options?
-
-There are, this page from the chromium site lists a few other things you might want to try also: https://www.chromium.org/Home/chromium-security/deprecating-powerful-features-on-insecure-origins#TOC-Testing-Powerful-Features
+If you require a trusted local certificate, you should raise this with your project lead to outline the reasons for the requirements and discuss potential solutions. Setting up a local CA should be considered a last resort, though documented solutions to do this are easily found online you should carefuly consider the risks. 

docs/skeleton/quickstart.md

@@ -11,9 +11,7 @@
 
 ## TL;DR
 
-If you just want a ready to go environment you can just use the following commands, if you're after more detail read
-the [docker setup](docker-setup.md) or [non docker setup](non-docker-setup.md) docs instead
-
+If you just want a ready to go environment you can just use the following commands. 
 
 ```
 bin/install [project_name] [docker_network_name] [php_version]
@@ -27,23 +25,4 @@ bin/install [project_name] [docker_network_name] [php_version]
 
 > Note: This will start the containers in detached mode, use `docker-compose stop` if you wish to stop them.
 
-<details>
-<summary>Install details</summary>
-
-```
-cp .env.dist .env; cp ./docker/database/.env.dist ./docker/database/.env; cp ./docker/app/.env.dist ./docker/app/.env;
-docker network create --subnet=192.168.35.0/24 boxuk-docker;
-docker-compose stop;
-docker-compose build;
-docker-compose up -d;
-bin/docker/composer install;
-cp wp-content/plugins/memcached/object-cache.php wp-content/object-cache.php;
-bin/docker/wp core install --url="https://$PROJECT_NAME.local" --title="Box UK WordPress Project" --admin_user=admin [email protected] --skip-email;
-bin/docker/wp site empty;
-bin/docker/wp dictator impose site-state.yml;
-bin/docker/wp package install [email protected]:nlemoine/wp-cli-fixtures.git;
-bin/docker/wp fixtures load;
-bin/docker/wp cache flush;
-echo '127.0.0.1 $PROJECT_NAME.local | sudo tee -a /etc/hosts;
-```
-</details>
+If you're after more detail read the [docker setup](docker-setup.md) or [non docker setup](non-docker-setup.md) docs instead.

docs/skeleton/troubleshooting.md

@@ -2,12 +2,10 @@
 
 ## WP install fails
 
-Sometimes the WordPress install in the `bin/install` script can fail. This is usually fixed by increasing the sleep time:
+Sometimes the WordPress install in the `bin/install` script can fail. This is usually fixed by increasing the sleep time to allow the MySQL server to start accepting connections.
 
 ```bash
 # ...
-echo 'Please hold...';
-
 sleep 10; # Increase this and retry, it may need to go as high as 30.
 # ...
 ```
@@ -16,22 +14,16 @@ sleep 10; # Increase this and retry, it may need to go as high as 30.
 
 > ERROR: readlink /var/lib/docker/overlay2: invalid argument
 
-Often this is due to a corrupted image that needs to be rebuilt sans cache.
+Often this is due to a corrupted image that needs to be rebuilt without any caches.
 
 `docker-compose build --no-cache`
 
 Or you can amend the install script to include the `--no-cache` option, e.g.
 
 ```diff
- if [ ! -z "${STYLEGUIDE_DIR}" ]; then
--    docker-compose -f docker-compose.yml -f docker-compose-styleguide.yml build;
-+    docker-compose -f docker-compose.yml -f docker-compose-styleguide.yml build --no-cache;
-     docker-compose -f docker-compose.yml -f docker-compose-styleguide.yml up -d;
- else
 -    docker-compose build;
 +    docker-compose build --no-cache;
      docker-compose up -d;
- fi
 ```
 
 ## Permission errors
@@ -45,10 +37,6 @@ If you are on a Linux machine, you will need to uncomment the following within t
 
 > Note: You will need to stop and rebuild the containers when changing env vars, e.g. `docker-compose stop; docker-compose up --build`
 
-## Certificate warnings
-
-On chrome you will need to type `thisisunsafe` to bypass the certificate warning (make sure your cursor isn't in the url bar). Othe browsers usually give you a button you can use to bypass.
-
 ## Slow local env
 
 ## Composer autoloader optimisations