Merge pull request #302 from boxuk/BWP-117

[BWP-117] Migrated Documentation

Author: James Amner

.github/workflows/docs.yml

@@ -0,0 +1,26 @@
+name: Publish Docs
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    name: Publish to retype branch
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        name: Checkout
+      - uses: actions/setup-dotnet@v1
+        name: Setup
+        with:
+          dotnet-version: 7.0.x
+      - uses: retypeapp/action-build@latest
+        name: Build
+      - uses: retypeapp/action-github-pages@latest
+        name: Publish
+        with:
+          update-branch: true

docs/index.md

@@ -0,0 +1,107 @@
+# Docker Setup
+
+If you just want a ready to go docker environment you can just use the [quickstart](quickstart.md), do read on though if you're after more detail.
+
+### Pre-requisites
+#### Pre-requisites for Windows systems
+* [WSL](https://docs.microsoft.com/en-us/windows/wsl/install)
+* [Linux Kernel Update Package](https://docs.microsoft.com/en-gb/windows/wsl/install-manual#step-4---download-the-linux-kernel-update-package)
+* [Cygwin](https://cygwin.com/install.html) (be sure to include the gettext package on install)
+#### Pre-requisites for all systems
+* [Docker](https://www.docker.com/)
+* [Docker compose](https://docs.docker.com/compose/install/)
+
+### Env Vars
+
+You will also need to set up a bunch of environment variables
+
+#### .env
+
+Create a `.env` file based on `.env.dist`.
+
+On Linux systems you will want to set `USER_ID` and
+`GROUP_ID` to the uid/gid of your primary user. These
+do not need to be set on Windows/Mac systems.
+
+#### ./docker/database/.env
+
+Create the `.env` file baed on `.env.dist`.
+
+It is recommended to change the default passwords even
+for development environments.
+
+#### ./docker/app/.env
+
+Create the `.env` file based on `.env.dist`.
+
+It is recommended to change the default passwords even
+for development environments.
+
+> Env vars declared here will override any vars declared in the `.env` file in the root. See the header comment within the root `.env.dist` for an explanation as to why, baring in mind that in this context the 'real' environment is docker.
+
+### Hosts file entries
+
+`127.0.0.1 $PROJECT_NAME.local`
+
+> If you want to change this you can, but you will need to make a change to `WP_HOME` in `./docker/app/.env`.
+
+### Create environment
+
+* `docker network create --subnet=192.168.35.0/24 $DOCKER_NETWORK_NAME`
+
+> The docker network is required to ensure the loopback works with the expected IP address.
+
+* `docker-compose build`
+
+> This only needs to be called once to build the image(s)
+
+* Use `docker-compose up` to build the containers. You'll only need to use this the first time.
+
+* Use `docker-compose start` to start the container
+
+* Use `docker-compose stop` to stop the container (without removing the volumes).
+
+> Using docker-compose down stops containers but also removes them. This will lead to loss of data (e.g. your database).
+
+That's it! You should now be able to browse to `https://$PROJECT_NAME.local` (or whatever you set) and view the site. Note, at time of writing you will need to go through the install script to have WordPress set up.
+
+
+### Running with Mac (And Docker Desktop)
+
+#### Xdebug
+
+We are running 2 app containers. By default, you will be using an xdebug-free container.
+This speeds up local env in browser and CLI as they no longer run xdebug for every request.
+
+**Setup**
+
+ - Download a browser extension for your browser from https://www.jetbrains.com/help/phpstorm/2020.2/browser-debugging-extensions.html
+ - Configure the browser extension to make sure the IDE key matches the one set in your `./docker/app/.env` (by default it is `wordpress`)
+
+![Settings](./assets/browser-xdebug-helper-0.png)
+
+ - Ensure your IDE is set up correctly. Screenshots below show PhpStorm setup as an example.
+
+![Settings](./assets/phpstorm-xdebug-0.png)
+
+![Debugger](./assets/phpstorm-xdebug-1.png)
+
+![Server](./assets/phpstorm-xdebug-2.png)
+
+ - To run xdebug in the browser: enable it in your IDE; add breakpoints; then go to your browser; enable xdebug in the browser extension (from first step of the setup) and reload the page.
+ - To run xdebug in CLI: enable it in your IDE; add breakpoints; then execute the CLI command:
+
+```
+     docker-compose exec --user www-data app_xdebug php index.php
+```
+
+Or, use one of the helper scripts located in `./bin/docker/xdebug`
+
+> On linux, remember to set `remote_host` to `192.168.35.1`
+
+### Running composer or wp-cli
+
+If you wish to run composer or wp-cli there are two bin scripts that will allow you to run directly on the container:
+
+`bin/docker/composer`
+`bin/docker/wp`

docs/skeleton/assets/browser-xdebug-helper-0.png

@@ -0,0 +1,23 @@
+# Fixtures
+
+We are using [wp-cli-fixtures](https://github.com/nlemoine/wp-cli-fixtures) for fixtures.
+
+## Install
+
+`./bin/docker/wp package install [email protected]:nlemoine/wp-cli-fixtures.git`
+
+## Usage
+
+Fixtures can be added to `./fixtures.yml` see readme of [wp-cli-fixtures](https://github.com/nlemoine/wp-cli-fixtures) for more info.
+
+## Load fixtures
+
+Fixtures can be loaded with the following command:
+
+`./bin/docker/wp fixtures load`
+
+## Delete fixtures
+
+If you wish to delete fixtures you've previously loaded, you can do so via:
+
+`./bin/docker/wp fixtures delete`

docs/skeleton/assets/logo.svg

@@ -0,0 +1,61 @@
+# HTTPS
+
+As part of the nginx docker container we set up a self-signed certificate. This allows us to access the site locally using HTTPS. We do this, because all our websites are served over HTTPS and so we want to ensure we are doing the same locally.
+
+The issue with self-signed certificates is browsers (quite rightly) deem them unsafe. You should too. **You should only bypass the security warnings of your browser if you are working on a secure network**.
+
+## 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).
+
+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