docs: Integrate with readthedocs.org

This patch adds configuration to integrate with readthedocs.org, using
mkdocs as rendering engine.

It also does minor documentation updates, to tidy some things up
(clearer titles, move some documentation from the root into docs/, etc).

docs/howto.md

@@ -1,5 +1,5 @@
 
-# Setting up an email server with Debian, dovecot and chasquid
+# chasquid how-to guide
 
 This is a practical guide for setting up an email server for personal or small
 groups use. It does not contain many explanations, but includes links to more

docs/index.md

@@ -0,0 +1,24 @@
+
+# chasquid
+
+[chasquid](https://blitiri.com.ar/p/chasquid) is an SMTP (email) server with a
+focus on simplicity, security, and ease of operation.
+
+This is the documentation index.
+
+Please see the [project page](https://blitiri.com.ar/p/chasquid) for more
+details.
+
+
+## Contact
+
+If you have any questions, comments or patches please send them to the [mailing
+list](https://groups.google.com/forum/#!forum/chasquid),
+chasquid@googlegroups.com.
+
+To subscribe, send an email to chasquid+subscribe@googlegroups.com.
+
+You can also reach out via IRC, `#chasquid` on
+[freenode](https://freenode.net/).
+
+

docs/install.md

@@ -0,0 +1,111 @@
+
+# Installing and configuring [chasquid](https://blitiri.com.ar/p/chasquid)
+
+## Installation
+
+If you're using Debian or Ubuntu, chasquid can be installed by running
+`sudo apt install chasquid`.
+
+To get, build and install the source, you will need a working
+[Go](http://golang.org) environment.
+
+```shell
+# Get the code and build the binaries.
+go get blitiri.com.ar/go/chasquid
+cd "$GOPATH/src/blitiri.com.ar/go/chasquid"
+make
+
+# Install the binaries to /usr/local/bin.
+sudo make install-binaries
+
+# Copy the example configuration to /etc/chasquid and /etc/systemd, and create
+# the /var/lib/chasquid directory.
+sudo make install-config-skeleton
+```
+
+
+## Configuration
+
+The configuration is in `/etc/chasquid/` by default, and has the following
+structure:
+
+```
+- chasquid.conf      Main config file.
+
+- domains/           Domains' data.
+  - example.com/
+    - users          User and password database for the domain.
+    - aliases        Aliases for the domain.
+  ...
+
+- certs/             Certificates to use, one dir per pair.
+  - mx.example.com/
+    - fullchain.pem  Certificate (full chain).
+    - privkey.pem    Private key.
+  ...
+```
+
+Note the certs/ directory layout matches the one from certbot,
+[letsencrypt](https://letsencrypt.org)'s
+default client, so you can just symlink `certs/` to `/etc/letsencrypt/live`.
+
+Make sure the user you use to run chasquid under ("mail" in the example
+config) can access the certificates and private keys.
+
+
+### Adding users
+
+You can add users with:
+
+```
+chasquid-util user-add user@domain
+```
+
+This will also create the corresponding domain directory if it doesn't exist.
+
+
+### Checking your configuration
+
+Run `chasquid-util print-config` to parse your configuration and display the
+resulting values.
+
+
+### Checking your setup
+
+Run `smtp-check yourdomain.com`, it will check:
+
+* MX DNS records.
+* SPF DNS records (will just warn if not present).
+* TLS certificates.
+
+It needs to access port 25, which is often blocked by ISPs, so it's likely
+that you need to run it from your server.
+
+
+### Greylisting, anti-spam and anti-virus
+
+chasquid supports running a post-DATA hook, which can be used to perform
+greylisting, and run anti-spam and anti-virus filters.
+
+The hook should be at `/etc/chasquid/hooks/post-data`.
+
+
+The one installed by default is a bash script supporting:
+
+* greylisting using greylistd.
+* anti-spam using spamassassin.
+* anti-virus using clamav.
+
+To use them, they just need to be available in your system.
+
+For example, in Debian you can run the following to install all three:
+
+```
+apt install greylistd spamc clamdscan
+usermod -a -G greylist mail
+```
+
+Note that the default hook may not work in all cases, it is provided as a
+practical example but you should adjust it to your particular system if
+needed.
+

docs/man/index.md

@@ -0,0 +1,29 @@
+# Manual pages
+
+From the latest Debian package:
+
+- [chasquid(1)](https://manpages.debian.org/unstable/chasquid/chasquid.1):
+  the main binary.
+- [chasquid.conf(5)](https://manpages.debian.org/unstable/chasquid/chasquid.conf.5):
+  the configuration file and structure.
+- [chasquid-util(1)](https://manpages.debian.org/unstable/chasquid/chasquid-util.1):
+  the command-line utility helper.
+- [mda-lmtp(1)](https://manpages.debian.org/unstable/chasquid/mda-lmtp.1):
+  helper to integrate with LMTP delivery.
+- [smtp-check(1)](https://manpages.debian.org/unstable/chasquid/smtp-check.1):
+  SMTP setup checker.
+
+From the development branch (more likely to change, but useful when doing
+development or running experimental versions):
+
+- [chasquid(1)](https://github.com/albertito/chasquid/blob/next/docs/man/chasquid.1.pod):
+  the main binary.
+- [chasquid.conf(5)](https://github.com/albertito/chasquid/blob/next/docs/man/chasquid.conf.5.pod):
+  the configuration file and structure.
+- [chasquid-util(1)](https://github.com/albertito/chasquid/blob/next/docs/man/chasquid-util.1.pod):
+  the command-line utility helper.
+- [mda-lmtp(1)](https://github.com/albertito/chasquid/blob/next/docs/man/mda-lmtp.1.pod):
+  helper to integrate with LMTP delivery.
+- [smtp-check(1)](https://github.com/albertito/chasquid/blob/next/docs/man/smtp-check.1.pod):
+  SMTP setup checker.
+

docs/monitoring.md

@@ -31,7 +31,7 @@ endpoint for expvars).
 
 *Note these are still subject to change, although breaking changes will be
 avoided whenever possible, and will be noted in the [upgrading
-notes](../UPGRADING.md).*
+notes](upgrading.md).*
 
 List of exported variables:
 

docs/upgrading.md

@@ -0,0 +1,40 @@
+
+This file contains notes for upgrading between different versions.
+
+
+## 0.07 → 1.0
+
+No backwards-incompatible changes. No more are expected within this major
+version.
+
+
+## 0.06 → 0.07
+
+No backwards-incompatible changes.
+
+
+## 0.05 → 0.06
+
+No backwards-incompatible changes.
+
+
+## 0.04 → 0.05
+
+No backwards-incompatible changes.
+
+
+## 0.03 → 0.04
+
+No backwards-incompatible changes.
+
+
+## 0.02 → 0.03
+
+* The default MTA binary has changed. It's now maildrop by default.
+  If you relied on procmail being the default, add the following to
+  /etc/chasquid/chasquid.conf: `mail_delivery_agent_bin: "procmail"`.
+
+* chasquid now listens on a third port, submission-on-TLS.
+  If using systemd, copy the `etc/systemd/system/chasquid-submission_tls.socket`
+  file to `/etc/systemd/system/`, and start it.
+