aerogramme.deuxfleurs.fr/content/documentation/quick-start/_index.md

+++ title = "Quick Start" weight = 0 sort_by = "weight" template = "documentation.html" +++

This quick start guide is specifically written with docker and docker-compose to make it more tangible. But nothing prevent your from deploying Aerogramme in production without docker or on other OS like FreeBSD.

Pull an image

Go to the download page, select a version and follow the instruction steps:

Download

Do the same for Garage, as Aerogramme can't run without Garage.

Prepare your environment

Create a deployment folder:

mkdir /tmp/mailstack && cd /tmp/mailstack

/tmp is used as the quick start guide assume you want to evaluate Aerogramme, not deploy it in production. Follow the cookbook for a production deployment.

Add a docker-compose.yml file inside it:

version: "3.9"
services:
  aerogramme:
    image: registry.deuxfleurs.org/aerogramme:{{TAG}}
    volumes: 
      - ./aerogramme.toml:/etc/aerogramme.toml
    ports:
      - 1143:1143 # IMAP
      - 2424:2424 # LMTP
  garage:
    image: docker.io/dxflrs/garage:{{TAG}}
    volumes: 
      - ./garage.toml:/etc/garage.toml

Create empty configuration files for now (they will be filled later but docker requires them now):

touch aerogramme.toml garage.toml

Do not forget to replace {{TAG}} by the tag you chose!

Setup Garage

Create a basic configuration file for Garage:

cat > garage.toml <<EOF
metadata_dir = "/tmp/meta"
data_dir = "/tmp/data"
replication_mode = "none"
rpc_bind_addr = "[::]:3901"
rpc_secret = "$(openssl rand -hex 32)"
[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
[k2v_api]
api_bind_addr = "[::]:3904"
EOF

Start Garage:

docker compose up -d garage

Configure Garage:

alias garage="docker compose exec -ti garage /garage"
garage layout assign -z dc1 -c 1 -t aero -- $(garage node id -q)
garage layout show
garage layout apply --version 1 # version number can change
garage key new --name aerogramme-global-key 
# note the "Key ID" and the "Secret Key"
garage bucket create aerogramme
garage bucket allow --read --write --key aerogramme-global-key aerogramme

If you are struggling with Garage configuration, maybe start with Garage's own quick start.

Setup Aerogramme

Aerogramme also has a configuration file:

s3_endpoint = "garage:3900" # use docker addressing
k2v_endpoint = "garage:3904" # same
aws_region = "garage"

[lmtp]
bind_addr = "[::]:2424"
hostname = "aerogramme.tld"

[imap]
bind_addr = "[::]:1143"

[login_static]
global_bucket = "aerogramme" # bucket created earlier
global_aws_access_key_id = "GK..." # shown when key "aerogramme-global-key" was created
global_aws_secret_access_key = "..." # same

[login_static.users]
# empty currently

Start the server as follow:

docker compose up -d aerogramme

Create a static user

Let's create an alias for aerogramme too:

alias aerogramme="docker compose exec -ti aerogramme /aerogramme"
aerogramme

You must start by creating a user profile in Garage. Run the following command after adjusting the parameters to your configuration:

aerogramme first-login --static alice

The program will interactively ask you some questions and finally generates for you a snippet of configuration:

Append the following section to your .toml configuration file:

[login_static.users.alice]
password = "$argon2id$v=19$m=4096,t=3,p=1$..."
user_secret = "..."

Note: user-secret is not the user's password. It is an additional secret used when deriving user's secret key from their password. The idea is that, even if user leaks their password, their encrypted data remain safe as long as this additional secret does not leak. You can generate it with openssl for example: openssl rand -base64 30. Read Cryptography & key management for more details.

Restart the server to load the new configuration:

docker compose up -d --force-recreate aerogramme

Validate

Now that your Aerogramme server is running,

Inject emails

Inject test emails:

./test/inject_emails.sh '<me@aerogramme.tld>' dxflrs

replace with netcat

Check with netcat

Todo

Check with mutt

Now you can connect your mailbox with mutt. Start by creating a config file, for example we used the following ~/.muttrc file:

set imap_user = quentin
set imap_pass = p455w0rd
set folder = imap://localhost:1993
set spoolfile = +INBOX
set ssl_starttls = no
set ssl_force_tls = no
mailboxes = +INBOX
bind index G imap-fetch-mail

And then simply launch mutt. The first time nothing will happen as Aerogramme must process your incoming emails. Just ask mutt to refresh its view by pressing G (for Get).

Now, you should see some emails:

And you can read them: