Quickstart mailserver

Tutorial on how to set up your BitMealum server and client.

(still much in progress, so not everything might work)

On a server with a public IP

1. Generate your server configuration

    ./bm-config init-config --server
   

   This will generate a template server-config.yml. Make sure you configure these settings properly, but the default settings should be secure enough. Note that you will need to change the config.server.host setting to either your public IP or 0.0.0.0 if you want to listen on all interfaces.

2. Obtain a server certificate and key for your given hostname by either generating self-signed or valid certificates through Let's Encrypt:

   2A) You can generate your own self-signed certificates by using:

    ./bm-config generate-cert --domain <bitmaelum.example.org>
   

   The certificates are stored in server.cert and server.key. Make sure you point to these files in your server-config.yaml file. Note that running with self-signed certificates is NOT RECOMMENDED as other mail-servers can deny mail from servers with invalid or self-signed certificates. (@TODO: certificates should be stored on the configured paths if they don't exist yet)

   2B) You can generate letsencrypt certificates by using:

   ./bm-config letsencrypt

   Note that for LetsEncrypt you need to have an open port 80 to the outside world. This most likely means you need root permission as well. It's possible to setup a proxy to a non-privileged port and use the -p option, but from the outside world, port 80 MUST be used.

3. Run the mail server:

     ./bm-server
   

   This will start the server. Test the server by running an HTTP request to it:

      curl 127.0.0.1:2424
   

   This should return a nice BitMaelum logo and some info.

4. Invite a new address to register on the server:

     ./bm-config create-invite <address\!>
   

   This will result in a token which you need to use when registering your account locally.

On your local computer

Set up your email account and register it to your mail server:

1. Generate a client configuration and change its settings according to your needs.

     ./bm-config init-config --client
   

2. Create a new mail account:

     ./bm-client account create <address\!> <mailserver>
   

   This will ask all kinds of questions in order to set up your account and register it at your mail-server. Note that you will need the invitation token as generated on the mail-server.

The invitation token only works for the specified address and is not valid for any other address. Tokens are also valid for a default of 30 days.

3. Send out a test email to the global bouncer to see if things work:

    ./bm-client message send --from "<address\!>" --to "hello\!" --subject "New account created"
   

   This will return a response message back to your address.

4. Read your email:

    ./bm-client message read -a <address\!>
   

5. All done. You've just sent and received your first BitMaelum message!