git » chasquid » commit 0f7fb6b

docs: Split install instructions out of the README

author Alberto Bertogli
2018-03-02 19:56:17 UTC
committer Alberto Bertogli
2018-03-02 19:56:17 UTC
parent 12b856a387173d43b6299fd4ffeabc3fffdb0f45

docs: Split install instructions out of the README

To keep documentation more organized, this patch splits the install
instructions to its own file, and references it from the README file.

INSTALL.md +111 -0
README.md +3 -105

diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..71f7c2b
--- /dev/null
+++ b/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.
+
diff --git a/README.md b/README.md
index cb1fd50..14726d9 100644
--- a/README.md
+++ b/README.md
@@ -54,110 +54,8 @@ You can also browse the
 [archives](https://groups.google.com/forum/#!forum/chasquid).
 
 
+## Documentation
 
-## Installation
-
-If you're using Debian or Ubuntu, chasquid can be installed by running
-`sudo apt install chasquid`.
-
-To get the code and build it, 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 matches certbot's structure, so if you use it you
-can just symlink 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.
+Check out the [how-to](docs/howto.md) or the [installation guide](INSTALL.md)
+for more details on how to install and configure chasquid.