From dd613d3c0fc70424c1677d51ea0897648135b9ce Mon Sep 17 00:00:00 2001 From: Benjamin Pelletier Date: Sat, 14 Mar 2026 09:45:11 -0700 Subject: [PATCH] Bring deployment playbook information back into repo --- README.md | 30 +++++++++++------ playbooks/README.md | 5 +++ playbooks/deployment.md | 75 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 99 insertions(+), 11 deletions(-) create mode 100644 playbooks/README.md create mode 100644 playbooks/deployment.md diff --git a/README.md b/README.md index 0187f3a..4a6e335 100644 --- a/README.md +++ b/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 diff --git a/playbooks/README.md b/playbooks/README.md new file mode 100644 index 0000000..6437d7a --- /dev/null +++ b/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. diff --git a/playbooks/deployment.md b/playbooks/deployment.md new file mode 100644 index 0000000..11c1ee9 --- /dev/null +++ b/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 get_sql_backup_legacy` +1. Get `images` folder + 1. If transferring from an old server, run `python3 deploy_tool.py 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= +export RW_ROOT_DB_PASSWORD= +export RW_SMTP_USERNAME= +export RW_SMTP_PASSWORD= +``` + +## Deploy site + +1. Build the necessary images: `python3 deploy_tool.py dc build` +1. Make password variables accessible in the terminal: `source ~/rw_passwords.sh` +1. Create an empty database using `python3 deploy_tool.py create_db` +1. Restore content into database using `python3 deploy_tool.py restore_db` + 1. Or, for a development deployment, create a minimal database using `python3 deploy_tool.py restore_empty_db` +1. Bring site up with `python3 deploy_tool.py start_site` +1. (Optional) Confirm that the webserver container is working, apart from the reverse proxy, by + visiting `http://:8080` +1. Confirm that the site is working via HTTP by visiting `http://` +1. Enable TLS with `python3 deploy_tool.py 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://` + 1. Create cronjob to automatically update certificates + 1. From this working directory, run `python3 deploy_tool.py add_cert_cronjob` + 1. To edit or delete crontabs, `crontab -e`