server

77ec29b

Author: myr (myr@terminal.pink)

Date: Mon Aug 26 20:58:33 2024 -0300

Parent: 6982a51

Improved docs a little

Diff

doc.go

diff --git a/doc.go b/doc.go
index 57cd3d8..d0a6e97 100644
--- a/doc.go
+++ b/doc.go
@@ -1,11 +1,7 @@
 // server is a SMTP server that is simple to setup and use.
 //
-// The binary is the main server, it is configured using a single config
-// file which should be located in ~/.config/dovel/config.json. This server is
-// responsible to receive your emails and save them according to your hooks.
-//
-// The structure of this config file is [Config]. See that doc for more
-// info.
+// The binary is the main server, this server is responsible to receive your
+// emails and save them according to your hooks. As well as sending them.
 //
 // # Setting up your email server
 //
@@ -20,15 +16,44 @@
 //   - 465: is marked as deprecated.
 //   - 587: is also official by RFC, this port is used for TLS encrypted mail.
 //
-// The current recomendation is to use port 586. Dovel works with any port,
+// The current recomendation is to use port 587. Dovel works with any port,
 // and the value must be set in the port field of the config file. To
 // configure this server see [Config].
 //
-// To receive email only the MX record is enough. Everytime dovel receives an
-// email it searches for an executable file in $XDG_CONFIG_DIR/dovel/hooks/
-// named receive-DOMAIN, for the DOMAIN receiving the email and executes it
-// passing the email in mbox format as standard input. Then it is up to the
-// script to decide what to do. See the scripts repo for examples.
+// # Server configuration
+//
+// This section is dedicated to help you correctly run your dover server. The
+// configuration is done using a single config file which should be located
+// in $XDG_CONFIG_DIR/dovel/config.json which normaly expands to
+// ~/.config/dovel/config.json. 
+// The structure of this config file is [model.Config]. See that doc for more
+// details. The following example should be enough to receive emails:
+//
+//	{
+//		"Port": "2525",
+//		"Domain": "my.domain",
+//		"ReadTimeout": 30,
+//		"WriteTimeout": 30,
+//		"MaxMessageBytes": 5000000,
+//		"MaxRecipients": 5,
+//		"Certificate": "fullchain.pem",
+//		"PrivateKey": "privkey.pem"
+//	}
+//
+// Note that Certificate and PrivateKey are given so that your server can use
+// TLS connections, this is desired for enhanced security. In cases where
+// proxies are used in front of servers, for doing the TLS handshake, setting
+// certificates here is not necessary.
+//
+// # Receiving emails
+//
+// To receive email the MX record must be correctly set on your registrar,
+// make sure it is pointing to your server where dover is running. Everytime
+// dovel receives an email it searches for an executable file in
+// $XDG_CONFIG_DIR/dovel/hooks/ named receive-DOMAIN, for the DOMAIN receiving
+// the email and executes it passing the email in mbox format as standard
+// input. Then it is up to the script to decide what to do. See the scripts
+// repo for examples, one simple is given in the next section.
 //
 // # Hooks
 //
@@ -37,9 +62,11 @@
 // receive-<DOMAIN> in the hooks folder with the following content:
 //
 //	#!/bin/sh
-//	cat > ~/mail/dovel.mbox
+//	cat >> ~/mail/dovel.mbox
 //
-// Be sure to make the file executable.
+// Be sure to make the file executable. Now whenever an email to the domain
+// DOMAIN it will be appended to the ~/mail/dovel.mbox file, which you can
+// later open and read.
 //
 // # Configuring DNS records
 //
@@ -58,11 +85,36 @@
 // # Sending email
 //
 // Dovel also sends email, for that it needs a valid VaultFile path on the
-// config. That means you need at least one user descrived on the json file.
-// The format of that file is a JSON array of the [User] struct.
+// config. That means you need at least one user described on the json file.
+// The format of that file is a JSON array of the [model.User] struct. Here's
+// one example:
+//
+// 	[
+// 		{
+// 			"Name": "user1@my.domain",
+// 			"PrivateKey": "dkim.priv",
+// 			"Password": "1234"
+// 		}
+// 	]
+//
+// This means the user1@my.domain is allowed to send emails, also as its DKIM
+// key was passed it will be used to sign the email using the DKIM guidelines.
+// This is optional.
+//
+// You can use any email client to communicate with your dovel server. When an
+// email comes from the domain configured, Dovel will known you want to send
+// the email, and will check if the sending user is valid using the configured
+// users, in positive case the email is sent, and the hook named send-<DOMAIN>
+// for the domain used is run passing the sent email as input.
+// The success of this hook does not impact one the sent email, it is mainly
+// used for storing it.
+//
+// # Debuging your server
+//
+// Dovel will issue debugging logs for the developer's convenience by setting
+// the DEBUG environment variable to any non-empty value at the time the server
+// is started, e.g.:
+//
+//	DEBUG=1 ./server
 //
-// Dovel is listening to connections on the port specified in the config file
-// use any email client to communicate with dovel. When an email comes from
-// the domain configured Dovel will check if the sending user is valid using
-// the Vault interface, in positive case the email is sent.
 package main