1 files changed, 87 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2cbab87
--- /dev/null
+++ b/README.md
@@ -0,0 +1,87 @@
+<!--
+SPDX-FileCopyrightText: 2024 Matthew Fennell <matthew@fennell.dev>
+
+SPDX-License-Identifier: AGPL-3.0-only
+-->
+
+# XMPP Server
+
+This playbook is for creating an XMPP server using prosody.
+
+I use this playbook for my own purposes; it will likely not generalise to other
+deployments.
+
+## Quickstart
+
+### Managed node initial setup
+
+Set up a server with the following things configured:
+
+* SSH access
+* DNS records (see [Prosody's docs](https://prosody.im/doc/dns) for more info)
+* `python3` installed
+
+Now, open the following firewall ports on the external firewall (the firewall
+on the box itself will be taken care of by the playbook):
+
+| Application | Protocol | Port |
+| ----------- | -------- | ---- |
+| SSH         | TCP      | 22   |
+| HTTP        | TCP      | 80   |
+| XMPP Client | TCP      | 5222 |
+| XMPP Server | TCP      | 5269 |
+
+### Install ansible on the control node
+
+Install the `ansible` package via your package manager.
+
+### Create a prod inventory file
+
+Create an inventory file in `inventory/prod.ini` with the production hosts that
+you would like to deploy to. For instance:
+
+```ini
+[xmpp_server]
+fennell.dev
+koyo.haus
+```
+
+### Create a staging inventory file
+
+Staging hosts can be useful to test deployment of your playbook before
+deploying to production. If you have staging hosts set up, you can use the
+Makefile to deploy to these first.
+
+Create an inventory file in `inventory/staging.ini` like the following:
+
+```ini
+[xmpp_server]
+staging.koyo.haus
+```
+
+### Run the playbook on your staging hosts
+
+```shell
+make staging
+```
+
+### If all goes well, run the playbook on your prod hosts
+
+```shell
+make prod
+```
+
+## Git hooks
+
+We provide sample git hooks in the `hooks` directory. To use these, ensure the
+following packages are installed:
+
+* gitlint
+* precious
+* reuse
+* shellcheck
+* yamllint
+
+```shell
+$ git config core.hooksPath hooks
+```