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:

<a
href="/download/"
title="Aerogramme releases"
class="group flex items-center justify-center space-x-1 font-semibold shadow hover:shadow hover:border-none border-none px-2 py-1.5 rounded text-white transition-all duration-500 bg-gradient-to-tl from-aerogramme-blue via-blue-500 to-blue-300 bg-size-200 bg-pos-0 hover:bg-pos-100">
<svg class="w-6 h-6 animate-pulse text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M9 19l3 3m0 0l3-3m-3 3V10"></path></svg>
<span class="hidden md:inline text-white">Download</span>
</a>

Do the same for [Garage](https://garagehq.deuxfleurs.fr/download/), as Aerogramme can't run without Garage.

## Prepare your environment

Create a deployment folder:

```bash
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:

```yml
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):

```bash
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:

```bash
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:

```bash
docker compose up -d garage
```

Configure Garage:

```bash
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](https://garagehq.deuxfleurs.fr/documentation/quick-start/).*

## Setup Aerogramme

Aerogramme also has a configuration file:

```toml
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:

```bash
docker compose up -d aerogramme
```


## Create a static user

Let's create an alias for aerogramme too:

```bash
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:

```bash
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](./crypt-key.md) for more details.*

Restart the server to load the new configuration:

```bash
docker compose up -d --force-recreate aerogramme
```

## Validate

Now that your Aerogramme server is running, 

### Inject emails

Inject test emails:

```bash
./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:

```ini
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:

![Screenshot of mutt mailbox](/screenshots/mutt_mb.png)

And you can read them:

![Screenshot of mutt mail view](/screenshots/mutt_mail.png)