Przeglądaj źródła

Some changes to readme

Thomas Buck 5 lat temu
rodzic
commit
0ecd31c159
1 zmienionych plików z 70 dodań i 39 usunięć
  1. 70
    39
      README.md

+ 70
- 39
README.md Wyświetl plik

@@ -1,16 +1,17 @@
1
-Introduction
2
-============
1
+# Sovereign
2
+# Introduction
3 3
 
4 4
 Sovereign is a set of [Ansible](http://ansible.com) playbooks that you can use to build and maintain your own [personal cloud](http://www.urbandictionary.com/define.php?term=clown%20computing) based entirely on open source software, so you’re in control.
5 5
 
6 6
 If you’ve never used Ansible before, you might find these playbooks useful to learn from, since they show off a fair bit of what the tool can do.
7 7
 
8
-The original author's [background and motivations](https://github.com/sovereign/sovereign/wiki/Background-and-Motivations) might be of interest. tl;dr: frustrations with Google Apps and concerns about privacy and long-term support.
8
+The original author's [background and motivations](https://github.com/sovereign/sovereign/wiki/Background-and-Motivations) might be of interest.
9
+tl;dr: frustrations with Google Apps and concerns about privacy and long-term support.
9 10
 
10
-Sovereign offers useful cloud services while being reasonably secure and low-maintenance. Use it to set up your server, SSH in every couple weeks, but mostly forget about it.
11
+Sovereign offers useful cloud services while being reasonably secure and low-maintenance.
12
+Use it to set up your server, SSH in every couple weeks, but mostly forget about it.
11 13
 
12
-Services Provided
13
------------------
14
+## Services Provided
14 15
 
15 16
 What do you get if you point Sovereign at a server? All kinds of good stuff!
16 17
 
@@ -24,7 +25,7 @@ What do you get if you point Sovereign at a server? All kinds of good stuff!
24 25
 -   Mobile push notifications and autodiscovery via [Z-Push](http://z-push.sourceforge.net/soswp/index.php?pages_id=1&t=home).
25 26
 -   Email client [automatic configuration](https://developer.mozilla.org/en-US/docs/Mozilla/Thunderbird/Autoconfiguration).
26 27
 -   Jabber/[XMPP](http://xmpp.org/) instant messaging via [Prosody](http://prosody.im/).
27
--   [Matrix](https://matrix.org/) via [Riot.im](https://about.riot.im).
28
+-   [Matrix](https://matrix.org/) via [Riot.im](https://about.riot.im) and [Synapse](https://matrix.org/docs/projects/server/synapse.html).
28 29
 -   The [Mastodon](https://mastodon.social/about) social network.
29 30
 -   An RSS Reader via [Selfoss](http://selfoss.aditu.de/).
30 31
 -   [CalDAV](https://en.wikipedia.org/wiki/CalDAV) and [CardDAV](https://en.wikipedia.org/wiki/CardDAV) to keep your calendars and contacts in sync, via [NextCloud](http://nextcloud.com/).
@@ -41,32 +42,29 @@ What do you get if you point Sovereign at a server? All kinds of good stuff!
41 42
 -   SSH configuration preventing root login and insecure password authentication
42 43
 -   A bunch of nice-to-have tools like [mosh](http://mosh.mit.edu) and [htop](http://htop.sourceforge.net) that make life with a server a little easier.
43 44
 
44
-Don’t want one or more of the above services? Comment out the relevant role in `site.yml`. Or get more granular and comment out the associated `include:` directive in one of the playbooks.
45
+Don’t want one or more of the above services? Comment out the relevant role in `site.yml`.
46
+Or get more granular and comment out the associated `include:` directive in one of the playbooks.
45 47
 
46
-Usage
47
-=====
48
+# Usage
48 49
 
49
-What You’ll Need
50
-----------------
50
+## What You’ll Need
51 51
 
52 52
 1.  A VPS (or bare-metal server if you wanna ball hard). My VPS is hosted at [Linode](http://www.linode.com/?r=45405878277aa04ee1f1d21394285da6b43f963b). You’ll probably want at least 512 MB of RAM between Apache, Solr, and PostgreSQL. Mine has 1024.
53 53
 2.  [64-bit Debian 9](http://www.debian.org/). (You can use whatever distro you want, but deviating from Debian will require more tweaks to the playbooks. See Ansible’s different [packaging](http://docs.ansible.com/ansible/list_of_packaging_modules.html) modules.)
54 54
 
55 55
 You do not need to acquire an SSL certificate.  The SSL certificates you need will be obtained from [Let's Encrypt](https://letsencrypt.org/) automatically when you deploy your server.
56 56
 
57
+## Installation
57 58
 
58
-Installation
59
-------------
60
-
61
-## On the remote server
59
+### On the remote server
62 60
 
63 61
 The following steps are done on the remote server by `ssh`ing into it and running these commands.
64 62
 
65
-### 1. Install required packages
63
+#### 1. Install required packages
66 64
 
67 65
     apt-get install sudo python
68 66
 
69
-### 2. Prep the server
67
+#### 2. Prep the server
70 68
 
71 69
 For goodness sake, change the root password:
72 70
 
@@ -87,30 +85,39 @@ Authorize your ssh key if you want passwordless ssh login (optional):
87 85
     chown deploy:deploy /home/deploy -R
88 86
     echo 'deploy ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/deploy
89 87
 
90
-Your new account will be automatically set up for passwordless `sudo`. Or you can just add your `deploy` user to the sudo group.
88
+Your new account will be automatically set up for passwordless `sudo`.
89
+Or you can just add your `deploy` user to the sudo group.
91 90
 
92 91
     adduser deploy sudo
93 92
 
94
-## On your local machine
93
+### On your local machine
94
+
95
+Ansible (the tool setting up your server) runs locally on your computer and sends commands to the remote server.
95 96
 
96
-Ansible (the tool setting up your server) runs locally on your computer and sends commands to the remote server. Install it as described in their [documentation](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html).
97
+#### 3. Software
97 98
 
98
-Download this repository somewhere on your machine, either through `Clone or Download > Download ZIP` above, `wget`, or `git` as below. Also install the dependencies for password generation.
99
+Download this repository somewhere on your machine, either through `Clone or Download > Download ZIP` above, `wget`, or `git` as below.
100
+Also install the dependencies for password generation as well as ansible itself.
99 101
     
100 102
     git clone https://github.com/xythobuz/sovereign.git
101 103
     cd sovereign
102 104
     sudo pip install -r ./requirements.txt
103 105
 
104
-### 4. Configure your installation
106
+#### 4. Configure your installation
105 107
 
106
-Modify the settings in the `group_vars/sovereign` folder to your liking. If you want to see how they’re used in context, just search for the corresponding string.
108
+Modify the settings in the `group_vars/sovereign` folder to your liking.
109
+If you want to see how they’re used in context, just search for the corresponding string.
107 110
 All of the variables in `group_vars/sovereign` must be set for sovereign to function.
108 111
 
109
-Finally, replace the `host.example.net` in the file `hosts`. If your SSH daemon listens on a non-standard port, add a colon and the port number after the IP address. In that case you also need to add your custom port to the task `Set firewall rules for web traffic and SSH` in the file `roles/common/tasks/ufw.yml`.
112
+Finally, replace the `host.example.net` in the file `hosts`.
113
+If your SSH daemon listens on a non-standard port, add a colon and the port number after the IP address.
114
+In that case you also need to add your custom port to the task `Set firewall rules for web traffic and SSH` in the file `roles/common/tasks/ufw.yml`.
110 115
 
111
-### 5. Set up DNS
116
+#### 5. Set up DNS
112 117
 
113
-If you’ve just bought a new domain name, point it at [Linode’s DNS Manager](https://library.linode.com/dns-manager) or similar. Most VPS services (and even some domain registrars) offer a managed DNS service that you can use for this at no charge. If you’re using an existing domain that’s already managed elsewhere, you can probably just modify a few records.
118
+If you’ve just bought a new domain name, point it at [Linode’s DNS Manager](https://library.linode.com/dns-manager) or similar.
119
+Most VPS services (and even some domain registrars) offer a managed DNS service that you can use for this at no charge.
120
+If you’re using an existing domain that’s already managed elsewhere, you can probably just modify a few records.
114 121
 
115 122
 Create `A` or `CNAME` records which point to your server's IP address:
116 123
 
@@ -125,10 +132,13 @@ Create `A` or `CNAME` records which point to your server's IP address:
125 132
 * `status.example.com` (for monit)
126 133
 * `matrix.example.com` (for riot)
127 134
 * `social.example.com` (for mastodon)
135
+* `comments.example.com` (for commento)
136
+* `iot.example.com` (for grafana)
128 137
 
129
-### 6. Run the Ansible Playbooks
138
+#### 6. Run the Ansible Playbooks
130 139
 
131 140
 First, make sure you’ve [got Ansible installed](http://docs.ansible.com/intro_installation.html#getting-ansible).
141
+This should already be done by running the pip requirements.txt from above.
132 142
 
133 143
 To run the whole dang thing:
134 144
 
@@ -136,30 +146,51 @@ To run the whole dang thing:
136 146
     
137 147
 If you chose to make a passwordless sudo deploy user, you can omit the `--ask-sudo-pass` argument.
138 148
 
139
-To run just one or more piece, use tags. I try to tag all my includes for easy isolated development. For example, to focus in on your firewall setup:
149
+To run just one or more piece, use tags.
150
+I try to tag all my includes for easy isolated development.
151
+For example, to focus in on your firewall setup:
140 152
 
141 153
     ansible-playbook -i ./hosts --tags=ufw site.yml
142 154
 
143
-You might find that it fails at one point or another. This is probably because something needs to be done manually, usually because there’s no good way of automating it. Fortunately, all the tasks are clearly named so you should be able to find out where it stopped. I’ve tried to add comments where manual intervention is necessary.
155
+You might find that it fails at one point or another.
156
+This is probably because something needs to be done manually, usually because there’s no good way of automating it,
157
+or because something changed in the upstream packages or you're not using Debian 9.
158
+Fortunately, all the tasks are clearly named so you should be able to find out where it stopped.
159
+I’ve tried to add comments where manual intervention is necessary.
160
+In the best case scenario, no manual steps should be needed, everything is done via the sovereign config vars.
144 161
 
145
-The `dependencies` tag just installs dependencies, performing no other operations. The tasks associated with the `dependencies` tag do not rely on the user-provided settings that live in `group_vars/sovereign`. Running the playbook with the `dependencies` tag is particularly convenient for working with Docker images.
162
+The `dependencies` tag just installs dependencies, performing no other operations.
163
+The tasks associated with the `dependencies` tag do not rely on the user-provided settings that live in `group_vars/sovereign`.
164
+Running the playbook with the `dependencies` tag is particularly convenient for working with Docker images.
146 165
 
147
-### 7. Finish DNS set-up
166
+#### 7. Finish DNS set-up
148 167
 
149 168
 Create an `MX` record for `example.com` which assigns `mail.example.com` as the domain’s mail server.
169
+To ensure your emails pass DKIM checks you need to add a `txt` record.
170
+The name field will be `mail._domainkey.EXAMPLE.COM.`
171
+The value field contains the public key used by DKIM.
172
+The exact value needed can be found in the file `/var/lib/rspamd/dkim/EXAMPLE.COM.mail.txt`.
173
+For DMARC you'll also need to add a `txt` record.
174
+The name field should be `_dmarc.EXAMPLE.COM` and the value should be `v=DMARC1; p=reject`.
175
+We will also add a `txt` record for SPF. This is now legacy, but some providers need it, so we provide an empty policy.
150 176
 
151
-To ensure your emails pass DKIM checks you need to add a `txt` record. The name field will be `default._domainkey.EXAMPLE.COM.` The value field contains the public key used by DKIM. The exact value needed can be found in the file `/var/lib/rspamd/dkim/EXAMPLE.COM.default.txt`. It will look something like this:
152
-
153
-    v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDKKAQfMwKVx+oJripQI+Ag4uTwYnsXKjgBGtl7Tk6UMTUwhMqnitqbR/ZQEZjcNolTkNDtyKZY2Z6LqvM4KsrITpiMbkV1eX6GKczT8Lws5KXn+6BHCKULGdireTAUr3Id7mtjLrbi/E3248Pq0Zs39hkDxsDcve12WccjafJVwIDAQAB
177
+For my DNS provider, that zonefile looks like this:
154 178
 
155
-For DMARC you'll also need to add a `txt` record. The name field should be `_dmarc.EXAMPLE.COM` and the value should be `v=DMARC1; p=none`. More info on DMARC can be found [here](https://dmarc.org).
179
+    @               IN MX 10 mail
180
+    @               IN TXT   "v=spf1 a:mail.example.com ?all"
181
+    _dmarc          IN TXT   "v=DMARC1; p=reject;"
182
+    mail._domainkey IN TXT   "v=DKIM1; k=rsa; p=INSERT_PUBLIC_KEY_HERE"
156 183
 
157
-Set up SPF and reverse DNS [as per this post](http://sealedabstract.com/code/nsa-proof-your-e-mail-in-2-hours/). Make sure to validate that it’s all working, for example, by sending an email to <a href="mailto:check-auth@verifier.port25.com">check-auth@verifier.port25.com</a> and reviewing the report that will be emailed back to you.
184
+Correctly set up reverse DNS for your server and make sure to validate that it’s all working,
185
+for example by sending an email to <a href="mailto:check-auth@verifier.port25.com">check-auth@verifier.port25.com</a>
186
+and reviewing the report that will be emailed back to you.
158 187
 
159
-### 8. Miscellaneous Configuration
188
+#### 8. Miscellaneous Configuration
160 189
 
161
-Sign in to the ZNC web interface and set things up to your liking. It isn’t exposed through the firewall, so you must first set up an SSH tunnel:
190
+Sign in to the ZNC web interface and set things up to your liking.
191
+It isn’t exposed through the firewall, so you must first set up an SSH tunnel:
162 192
 
163 193
 	ssh deploy@example.com -L 6643:localhost:6643
164 194
 
165 195
 Then proceed to http://localhost:6643 in your web browser.
196
+The same goes for the RSpamD web interface on port 11334.

Ładowanie…
Anuluj
Zapisz