1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
<!--
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
#### DNS
If the JID names match the domain of the server you are deploying to, create
the following DNS records:
| Type | Host | IP Address | TTL |
| -------- | ---- | ---------- | --------- |
| A Record | @ | Static IP | Automatic |
| Type | Host | Target | TTL |
| ------------ | ------ | ----------- | --------- |
| CNAME Record | upload | Root domain | Automatic |
See [Prosody's docs](https://prosody.im/doc/dns) for information on alternative
arrangements.
#### Firewall
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 |
| XEP-0065 | TCP,UDP | 5000 |
| XMPP Client | TCP | 5222 |
| XMPP Server | TCP | 5269 |
| HTTP Server | TCP | 5280 |
| HTTP Server | TCP | 5281 |
### 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 virtual_host=chat.fennell.dev
koyo.haus virtual_host=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
```
### Set variables in inventory files
Now, create a directory like the following for each of the hosts you have
defined: `inventory/host_vars/staging.koyo.haus/vars.yaml`
```
inventory/
├── host_vars
│ └── staging.koyo.haus
│ └── vars.yaml
└── staging.ini
```
```yaml
borg_passphrase: # the passphrase that borg will encrypt your repo with
borg_private_key_path: # e.g. /home/matthew/.ssh/some-key
borg_repo: # the repo to use, e.g. ssh://example.org/./repo
certbot_email: an email address letsencrypt should use if renewal fails
virtual_host: the domain of the JID you'd like to use, e.g. 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:
* ansible-lint
* gitlint
* precious
* reuse
* shellcheck
* yamllint
```shell
$ git config core.hooksPath hooks
```
|
