Merge pull request #302 from boxuk/BWP-117

[BWP-117] Migrated Documentation

.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/skeleton/docker-setup.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/fixtures.md

@@ -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/https.md

@@ -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

docs/skeleton/index.md

@@ -0,0 +1,60 @@
+# BoxUK WordPress Project Skeleton
+
+A base [WordPress project](https://github.com/boxuk/wp-project-skeleton) from Box UK to get you up and running quickly.
+
+
+## Installation
+
+Create a new project with composer
+
+```bash
+composer create-project boxuk/wp-project-skeleton my-project --stability=dev
+```
+
+Install with the simple install script
+
+```bash
+bin/install my-project
+```
+
+> Note: This is an interactive command.
+
+## Usage
+
+Frontend:
+
+[https://my-project.local](https://my-project.local)
+
+Admin:
+
+[https://my-project.local/wp-admin](https://my-project.local/wp-admin)
+
+
+If you need to update the admin password, you can run the following WP-CLI command:
+
+```sh
+bin/docker/wp user update admin --user_pass=your_password_here
+```
+
+## Features
+
+📕 - Fully [documented](https://github.com/boxuk/wp-packages/blob/main/docs/index.md).
+
+🐳 - Fully dockerized setup
+
+📦 - Composer based plugin management
+
+🧠 - [Genius xDebug setup](https://strayobject.medium.com/php-docker-and-xdebug-with-no-performance-loss-261ad89efd6e)
+
+📋 - [Dictator](https://github.com/boxuk/dictator/) support for dictating state across environments
+
+🪜 - Fixtures support using [wp-cli-fixtures](https://github.com/nlemoine/wp-cli-fixtures)
+
+🏋️‍♀️ - Optimised mu-plugin setup, including scaffold tool
+
+🚩 - First class support for feature flags using [wp-feature-flags](https://github.com/boxuk/wp-feature-flags)
+
+✅ - Unit, Integration and Visual Regression testing support
+
+> You can read more about all of these features in [this post on the Box UK blog](https://www.boxuk.com/insight/how-we-develop-wordpress-sites/).
+

docs/skeleton/non-docker-setup.md

@@ -0,0 +1,3 @@
+# Non Docker Setup
+
+Generally, we do not offer support for non-dockerised setups. However, running without docker should be fairly straightforward if you're familiar with running WordPress locally. You'll require PHP & Composer, a MySQL (or equivalent) server, and a web-server (Apache, Nginx etc). Set the document-root to the root of the project, and ensure your DB credentials are added to the relevant sections of your `.env` file. 

docs/skeleton/patched-plugins.md

@@ -0,0 +1,45 @@
+# Patched Plugins
+
+Sometimes a plugin you rely on doesn't work quite right and they either aren't on github or are just ignoring your submitted PR. In this scenario it's useful to 'patch' the plugin, i.e. make direct changes to the source of the plugin.
+
+Doing this directly in `wp-content/plugins` isn't safe because it can get reverted to the source easily with a composer install or update.
+
+Therefore, we offer a way of safely patching plugins by using a similar method to how we deal with premium plugins. By patching and thus installing from the `patched-plugins` directly we are controlling the patch in a confined way, with a neat install and upgrade path.
+
+> **IMPORTANT**: When we patch the plugin in this way, we are diverging from the original source and thus aren't able to easily install updates. Therefore, patching a plugin should be considered a last resort or a temporary measure until you're able to get back to the source.
+
+To patch a plugin, take the following steps:
+
+## Composer dependency
+
+* Move the plugin to `patched-plugins`
+
+`mv wp-content/plugins/plugin patched-plugins/plugin`
+
+* Make the change/patch required and record the diff to a file. This diff should be saved with the plugin, so that if we update the plugin to a newer version we can either re-apply the patch, _or_ if it's been fixed upstream move back to the un-patched version. 
+
+* Edit `patched-plugins/plugin/composer.json` (or add one if it doesn't exist, see [further down for an example](#adding-a-composer-json)) to include a patched version number, and ensure the namespace is set to `wp-patched-plugins/`.
+
+* Remove the original package
+
+```sh
+composer remove vendor/plugin
+composer require wp-patched-plugins/plugin-name
+```
+
+
+### Adding a composer.json
+
+* Add a `composer.json` into the directory, that should look like the following (note, if the plugin already has a `composer.json` you can just use that, just make sure you use the name from within their `composer.json`):
+
+```json
+{
+    "name": "wp-patched-plugins/plugin-name",
+    "type": "wordpress-plugin",
+    "require": {
+        "composer/installers": "~1.0"
+    },
+    "version": "<plugin-version>"
+}
+
+```

docs/skeleton/php-versions.md

@@ -0,0 +1,31 @@
+# PHP Versions
+
+The skeleton supports the following PHP versions:
+
+* 8.2 (default)
+* 8.3
+
+## Using docker
+
+When using docker you can easily decide which PHP version you want to use by setting the `PHP_VERSION` environment variable in the `.env` file.
+
+If you're using the `bin/install` script (recommended) then you can specify which version you want to run by passing a 4th option.
+For example, if you want to use PHP 8.3 you might run something like the following:
+
+`bin/install boxuk-wp-skeleton '' boxuk-docker 8.3`
+
+## Not using docker
+
+If you're not using docker it will use whichever version of PHP is installed on your system.
+
+## composer.lock issues
+
+We need to use `composer.lock` in the main because we are using composer for plugins. We need
+to ensure plugins are locked to specific versions. We can't trust that always updating plugins will work, we
+generally rely on dependabot to update our plugins, so we can review the changes as part of a PR and
+make a decision whether we want to upgrade or not.
+
+This presents a challenge if we need to change our version of PHP as our `composer.lock` file will be locked
+to the original PHP version we were using. This should be a rare occurrence but if you come across it you can solve
+by either updating each library individually which is causing issues or by doing a blanket `composer update` or by removing the
+lock file and running `composer install`.