This is the main dovel repository, it has the Go code to run dovel SMTP server.
Author: myr (myr@terminal.pink)
Date: Mon Aug 26 20:58:33 2024 -0300
Parent: 6982a51
Improved docs a little
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