diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 140 |
1 files changed, 0 insertions, 140 deletions
diff --git a/README.md b/README.md deleted file mode 100644 index 9afa85e..0000000 --- a/README.md +++ /dev/null @@ -1,140 +0,0 @@ -<!-- -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. - -For instance, it is only tested with Debian Stable running on both the control -and managed nodes. - -## Quickstart - -### Managed node initial setup - -Set up a server with the following things configured: - -#### Box - -The box needs: - -* SSH access to a user that can become root without a password -* `python3` installed - -### Install ansible on the control node - -Install the `ansible` package via your package manager. - -### Backup - -You will need to initialise a borg repository on some host or managed provider. - -Once you have done this, make a note of the private key you will use to access -the remote server and the address of the repo. - -Once borg is configured you should run - -```shell -sudo borgmatic init --encryption repokey -``` - -On the managed host. In the future, this should be done via the playbook -itself. - -### 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] -continuous.nonprod.koyo.haus -``` - -### Set variables in inventory files - -Now, create a directory like the following for each of the hosts you have -defined: `inventory/host_vars/continuous.nonprod.koyo.haus/vars.yaml` - -``` -inventory/ -├── host_vars -│ └── continuous.nonprod.koyo.haus -│ └── vars.yaml -└── staging.ini -``` - -```yaml -acme_account_uri_nonprod: # the staging uri we should add CAA records for -acme_account_uri_prod: # the prod uri we should add CAA records for -borg_private_key_path: # e.g. /home/matthew/.ssh/some-key -borg_repo: # the repo to use, e.g. ssh://example.org/./repo -cert_host: # the server that manages certs, e.g. matthew-server.local -delegate_prefix: # the subdomain that the A record should point to, e.g chat -desec_token: # the desec token we should use to update DNS records -virtual_host: # the domain of the JID you'd like to use, e.g. koyo.haus - -users: # the users you'd like to ensure exist - - name: # the username of the user, e.g. admin - password: # the password of the user - -borg_passphrase: # the passphrase that borg will encrypt your repo with -postgres_password: # the password that prosody will use to access the database -turn_secret: # the password prosody will use to interact with turn -``` - -### Run the playbook on your staging hosts - -```shell -make staging -``` - -### If all goes well, run the playbook on your prod hosts - -```shell -make prod -``` - -## External tools - -Certificates are generally managed by the `acme` project. In particular, -although this playbook does set the DANE hash based on the certificates found -on the `acme` server, it does not directly install any itself. This is to -prevent the playbook from overwriting already-renewed certifictes, that the -playbook is not aware of. - -## Git hooks - -We provide sample git hooks in the `hooks` directory. To use these, ensure the -following packages are installed: - -* ansible-lint -* gitlint -* precious -* reuse -* shellcheck -* yamllint - -```shell -$ git config core.hooksPath hooks -``` |