Bring deployment playbook information back into repo

README.md

@@ -2,24 +2,32 @@
 
 This repository contains the deployment framework for the RopeWiki backend infrastructure.
 
-At its hearth ropewiki is powered by [Mediawiki](https://www.mediawiki.org/wiki/MediaWiki) (the same as Wikipedia), along with an extension called [Semantic Mediawiki](https://www.semantic-mediawiki.org/wiki/Semantic_MediaWiki) which allows for meaningful connections between pieces of data.
-
-Detailed documentation previously located here has moved to the [GitHub wiki](https://github.com/RopeWiki/app/wiki/).
+At its heart ropewiki is powered by [Mediawiki](https://www.mediawiki.org/wiki/MediaWiki) (the same as Wikipedia), along with an extension called [Semantic Mediawiki](https://www.semantic-mediawiki.org/wiki/Semantic_MediaWiki) which allows for meaningful connections between pieces of data.
 
 _tl;dr - everything needed to make the site load lives here. What you actually see when the site loads does not live here._
 
+## Detailed documentation
+
+* [Playbooks](./playbooks)
+    * [Deployment](./playbooks/deployment.md)
+    * [Maintenance](https://github.com/RopeWiki/app/wiki/Maintenance)
+    * [Troubleshooting](https://github.com/RopeWiki/app/wiki/Troubleshooting)
+
+Additional documentation may be found in the [GitHub wiki](https://github.com/RopeWiki/app/wiki/).
+
 ## What lives here
 
 Using this repo you can build and deploy the complete stack of services needed to run the website.
 
-- deployment tools & helpers
-- docker configs
-- webserver & proxy server configs
-- mediawiki configs
-- mediawiki extensions & patches
-- version control for PHP, MySQL, MediaWiki, SMW
-- backup automation
-- mail relay config
+- [deployment tool](deploy_tool.py) & [helper](rw_helpers.sh)
+- [docker compose config](docker-compose.yaml)
+- [webserver config](webserver)
+    - [version control for PHP, MySQL, MediaWiki, SMW](webserver/Dockerfile)
+    - [mediawiki configs](webserver/html/ropewiki/LocalSettings.php)
+    - [mediawiki extensions](webserver/Dockerfile) (plus [modified extensions](webserver/html/ropewiki/extensions)) & patches
+- [proxy server config](reverse_proxy)
+- [backup automation](backup_manager)
+- [mail relay config](mailserver)
 
 ## What does not live here
 

playbooks/README.md

@@ -0,0 +1,5 @@
+# Playbooks
+
+## [Deployment](deployment.md)
+
+How to bring up an instance of RopeWiki in a production or development context.

playbooks/deployment.md

@@ -0,0 +1,75 @@
+# Site deployment
+
+Execute the steps below to produce a server running RopeWiki. The instructions assume an Ubuntu machine. On Windows, the
+easiest option is probably to install [VirtualBox](https://www.virtualbox.org/wiki/Downloads) and host a virtual Ubuntu
+system. Alternately, all of the steps after the firewall (which can be skipped) should be possible directly in a Windows
+command prompt as long as [Python 3](https://www.python.org/downloads/) is installed and added to
+the `PATH` (`python3 --version` to verify). Ignore all `apt` commands and instead perform the Windows alternative.
+
+## Protect the system
+
+1. Setup firewall from scratch
+    1. Block everything incoming (`sudo ufw default deny incoming`)
+    1. Allow everything outgoing (`sudo ufw default allow outgoing`)
+    1. Allow SSH to host machine (`sudo ufw allow OpenSSH`)
+    1. Allow web server requests (`sudo ufw allow 80/tcp && ufw allow 443/tcp`)
+    1. Allow SSH directly to containers (`sudo ufw allow 22001/tcp && ufw allow 22002/tcp`)
+    1. Optionally, allow debugging: (`sudo ufw allow 8080/tcp`)
+1. Alternately, setup firewall by importing rules
+    1. Copy `/etc/ufw/user.rules`
+    1. Copy `/etc/ufw/user6.rules`
+1. Enable firewall (`sudo ufw enable`)
+
+## Install necessary tools
+
+1. Update packages (`sudo apt-get update`)
+1. [Install docker](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository)
+    1. Fix [this issue](https://github.com/docker/compose/issues/6931)
+       with `sudo apt update && apt install rng-tools` (note: this may no longer be necessary with docker compose v2)
+    1. Verify installation with `docker compose version`; result should be 2.x.x
+1. Install git (`sudo apt-get install git`)
+1. Clone this repository into an appropriate folder (perhaps `/rw`)
+
+## Define site to be deployed
+
+1. Ensure that there is a .json file in [site_configs](../site_configs) corresponding to the site to be deployed
+1. Create a new .json file, modeled after [dev.json](../site_configs/dev.json), if necessary
+    1. Create a folder that will hold persistent mount data (perhaps `/rw/mount`) and define folders relative to that
+       folder
+1. SITE_NAME is the name of the .json file without extension (e.g., example.json implies a SITE_NAME of `example`)
+
+## Transfer site data
+
+1. Get latest SQL backup
+    1. If transferring from an old server, run `python3 deploy_tool.py <SITE_NAME> get_sql_backup_legacy`
+1. Get `images` folder
+    1. If transferring from an old server, run `python3 deploy_tool.py <SITE_NAME> get_images_legacy`
+1. Create a shortcut to declare passwords: create `~/rw_passwords.sh` (or another location) with content like:
+```shell
+#!/bin/bash
+# These are the mandatory environment variables needed to start a copy of the site
+export WG_DB_PASSWORD=<The password for the `ropewiki` DB user>
+export RW_ROOT_DB_PASSWORD=<The password for the `root` DB user>
+export RW_SMTP_USERNAME=<The username for logging into the smtp relay>
+export RW_SMTP_PASSWORD=<The password for logging into the smtp relay>
+```
+
+## Deploy site
+
+1. Build the necessary images: `python3 deploy_tool.py <SITE_NAME> dc build`
+1. Make password variables accessible in the terminal: `source ~/rw_passwords.sh`
+1. Create an empty database using `python3 deploy_tool.py <SITE_NAME> create_db`
+1. Restore content into database using `python3 deploy_tool.py <SITE_NAME> restore_db`
+    1. Or, for a development deployment, create a minimal database using `python3 deploy_tool.py <SITE_NAME> restore_empty_db`
+1. Bring site up with `python3 deploy_tool.py <SITE_NAME> start_site`
+1. (Optional) Confirm that the webserver container is working, apart from the reverse proxy, by
+   visiting `http://<hostname>:8080`
+1. Confirm that the site is working via HTTP by visiting `http://<hostname>`
+1. Enable TLS with `python3 deploy_tool.py <SITE_NAME> enable_tls`
+    1. Note that the certs should be persisted in `${proxy_config_folder}/letsencrypt`; select option 1 to reinstall the
+       existing cert if prompted
+    1. Enable redirection (option 2) when prompted
+    1. Verify success by visiting `https://<hostname>`
+    1. Create cronjob to automatically update certificates
+        1. From this working directory, run `python3 deploy_tool.py <SITE_NAME> add_cert_cronjob`
+        1. To edit or delete crontabs, `crontab -e`