Add local setup and engineering workflow doc templates

[fabiankaegy]

Summary

• Adds docs/local-setup.md — a project template for local setup documentation (prerequisites, snapshots/manual setup steps, screenshots)
• Adds docs/engineering-workflow.md — a project template for engineering workflow documentation (responsible parties, deployment workflow, hosting/server info, monitoring, third-party integrations)
• Updates docs/README.md to link to both new templates
• These replace the existing Google Docs templates, bringing the documentation into the repo itself

[fabiankaegy]

@10up/engineering-leadership Pinging all of you to discuss whether we want to move all of this into the repo and deprecate the Google Docs for them.

With agents I only see upsides to doing this. And even for humans it's easier to just get the link to the repo and have everything needed.

This will also make it more likely for them to be updated etc.

The only downside I see is that PM's won't be able to edit / audit it directly which might be an issue. So looking for your thoughts :)

[christianc1]

+1 to moving local setup docs to the repo. I don't know of many cases where PjMs are editing or auditing the local setup documentation, so for me, that's a non-issue.

[pdavies88]

@fabiankaegy is the thought process on this list is that it should be subtractive rather than additive for the tech lead?

[pdavies88]

@fabiankaegy nearly every project I've been on has had something to this effect in this section. Can thoughts why we may not want to include the additional details?

LS-3 Repeatable Steps
---------------------

Engineers should follow LocalWP Setup Method steps whenever possible. In some cases, manual setup may be necessary. Speak to your Technical Lead if you are having trouble setting up your local environment.

### LS-3.1 Steps - LocalWP Setup Method

Follow these steps to set up the local environment using [LocalWP](https://localwp.com/).

If you have other local dev environments (for example, XAMPP, docker, etc.) then make sure to quit those applications before proceeding, as they may cause conflicts with the internal DNS.

**Step 1**

Install the LocalWP application

If you have not done so already:

[Download the LocalWP application](https://localwp.com/) and install it on your machine. Local should work with Mac, Windows, and most Linux distributions.

**Step 2**

Add a new site by clicking the + at the lower-left corner of the screen.

Supply the following details: (we will overwrite the changes later)

* * * * *

What's your site's name?

PROJECTNAME

Advanced options › Local site domain

PROJECTNAME.local

Advanced options › Local site path

~/Local Sites/PROJECTNAME

Click the "Continue" button.

* * * * *

Choose your environment

Custom

PHP version

8.X.XX

Web server

nginx 1.XX.X

Database

MySQL 8.X.X

Click the "Continue" button.

WordPress username

<any>

WordPress password

<any>

WordPress email

<any>

Advanced options › Is this a WordPress Multisite?

PLEASE WRITE ANY OPTIONS REQUIRED FOR THIS STEP

Click the "Add Site" button.

**Step 3**

Clone the GitHub repository

Right-click on the "PROJECTNAME" site in Local, and select "Open Site Shell"

Run the following commands to delete the default /wp-content directory, clone the repository, and build the files:

rm -rf wp-content

git clone git@github.com:PROJECTNAME/PROJECTNAME.git wp-content\

**Step 4**

Import the database

-   Run the following commands to pull the latest snapshot:

-   wp snapshots search PROJECTNAME

-   ID: PROJECTNAME-HASH

-   wp snapshots pull <MOST_RECENT_SNAPSHOT_ID>

-   Do you want to pull files?\
    No

-   Do you want to pull the database?\
    Yes

-   Are you sure?\
    Yes

**Step 5**

Run these commands to set the WP constants ready for the local environment:

wp config set WP_DEBUG true --raw\
wp config set WP_DEBUG_LOG true --raw\
wp config set WP_DEBUG_DISPLAY false --raw\
wp config set SCRIPT_DEBUG true --raw\
wp config set WP_ENVIRONMENT_TYPE local\

**Step 6**

Trust the Local SSL

If you are experiencing issues with the SSL, follow these steps to trust the SSL certificate for your local installation:

-   [SSL Certificate on macOS](https://localwp.com/help-docs/getting-started/managing-local-sites-ssl-certificate-in-macos/#macos-keychain-access)

**Step 7**

-   Open a terminal and navigate to the wp-content folder, located at; [WP-root]/wp-content/ and then run the following command to add the requisite plugins.

-   composer install

-   Navigate to the themes folder, located at; [WP-root]/wp-content/themes/PROJECTNAME/ and then run the following commands to build the PROJECTNAME theme.

-   composer install

-   Navigate to the PROJECTNAME must-use plugin folder, located at; [WP-root]/wp-content/mu-plugins/PROJECTNAME/ and then run the following commands to build the PROJECTNAME core functionality.

-   composer install

-   Using WP-CLI, you will need to run the following command to ensure custom User permissions are set up.

-   wp PROJECTNAME roles update

-   Navigate to the wp-content folder, located at; [WP-root]/wp-content/ and then run the following command to build the assets.

-   npm install

-   npm run build

**Step 8**

Log in

Log into the admin area.

https://PROJECTNAME.local/wp-login.php\
Username: snapshots\
Password: password

[pdavies88]

@fabiankaegy same thing for Image Proxy this seems to always be a constant between projects:

LS-4 Image Proxy
----------------

The image proxy setup steps below assume you are using [LocalWP](https://localwp.com/).

Adding the image proxy configuration will try to display any missing images that are not present on your local install by loading them from the production server.

### LS-4.1 Image Proxy

**Step 1**

If you'd like to proxy images from a Local environment to production, do the following:

Go to ~/Local Sites/PROJECTNAME/conf/nginx and create a new file called uploads-proxy.conf 

Paste the following into the file and save.

location ~ ^/wp-content/uploads/(.*) {

    if (!-e $request_filename) {

        rewrite ^/wp-content/uploads/(.*) https://PRODUCTION-URL/wp-content/uploads/$1 redirect;

    }

}

**Step 2**

Then go open site.conf.hbs - and find the following lines:


# WordPress Rules

{{#unless site.multiSite}}

include includes/wordpress-single.conf;

{{else}}

include includes/wordpress-multi.conf;

{{/unless}}

Under that, add the following:

# Proxy requests to the upload directory to the production site

include uploads-proxy.conf;

Save file changes.

**Step 3**

Restart the LocalWP application.

1.  Visit the Local app

2.  Right-click the "PROJECTNAME" site

3.  Select "Restart"

**Step 4**

Test that it works successfully.

Visit the homepage. 

https://PROJECTNAME.local/

The media should now be proxying successfully.