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

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

This quickstart guide will teach you how to run an in-memory instance of Aerogramme,
because it is easier to run than a distributed real-world deployment. The goal here
is that you get familiar with the software, you understand what it does and what it does not,
so you can evaluate it. Once ready for a real deployment, you will find all the information you need in the [cookbook](@/documentation/cookbook/_index.md).

*Enjoy your reading!*

## What is Aerogramme

Aerogramme is a [Message Delivery Agent (MDA)](https://en.wikipedia.org/wiki/Message_delivery_agent) that speaks the [IMAP protocol](https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol).
It makes sure that your mailbox, and thus your emails, are stored safely and stay in sync across all your devices.
<!--It manages a bit more than just your emails, as contacts and calendars support is planned.-->

Aerogramme is not (yet) a [Message Transfer Agent (MTA)](https://en.wikipedia.org/wiki/Message_transfer_agent) as it does not speak the [SMTP protocol](https://fr.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol).
It means you can't send email for example with Aerogramme alone, you need to plug it to a MTA, like [Postfix](https://www.postfix.org/) or [opensmtpd](https://www.opensmtpd.org/).
The connection between Aerogramme and the MTA (Postix, opensmtpd, etc.) is done through a protocol named [LMTP](https://en.wikipedia.org/wiki/Local_Mail_Transfer_Protocol).

## Get a binary

Aerogramme is shipped as a static binary for Linux only on `amd64`, `aarch64` and `armv6` architectures.
For convenience, a docker container is also published both on Docker Hub and on Deuxfleurs' registry.
Also, Aerogramme is an open-source software released under the [EUPL licence](https://commission.europa.eu/content/european-union-public-licence_en), and you can compile it yourself from the source.

To get the latest version of Aerogramme and the precise download information, both for binary and source releases, go to the dedicated download page:

<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>

To check if the binary you got is working, just launch it without any parameter, and an help message should be displayed like this one:

```text
aerogramme 0.2.0
Alex Auvolat <alex@adnab.me>, Quentin Dufour <quentin@dufour.io>
A robust email server

USAGE:
    aerogramme [OPTIONS] <SUBCOMMAND>

...
```

## Starting the daemon in development mode

To start an in-memory daemon for evaluation purposes, you don't need any configuration file. Just run:

```bash
aerogramme --dev provider daemon
```

Now Aerogramme is listening for IMAP on `[::1]:1143` and for LMTP on port `[::1]:1025`. A test account has been created with username `alice` and password `hunter2`.

<!--
## Checking that the service is listening as intended

*If you don't have socat installed on your computer or are not comfortable with interacting
with low-level tools, you can simply skip this section.*

You can try to connect on both ports with `socat` and see a welcome message from the server (CTRL + D to exit):

```
$ socat - tcp:localhost:1143,crlf
* OK [CAPABILITY MOVE UIDPLUS LIST-STATUS ENABLE CONDSTORE LITERAL+ IDLE IMAP4REV1 UNSELECT] Aerogramme

$ socat - tcp:localhost:1025,crlf
220 example.tld Service ready
```

If you got these outputs, well done, your daemon is correctly started and is working!
-->

## Connecting Thunderbird

Now that we have Aerogramme acting as a Mail Delivery Agent, we want to connect our devices to it.
For this quick start guide, we will use Thunderbird on desktop. On the create account page,
start filling the fields.

**Your full name:** `Alice`  
**Email address:** `alice@example.tld`  
**Password:** `hunter2`  

Then click on **Configure Manually**. New fields will appear, fill them as follow.

**Protocol:** `IMAP`  
**Hostname:** `::1`  
**Port:** `1143`  
**Connection Security:** `None`  
**Authentication Method:** `Normal password`  
**Username:** `alice`  

*Aerogramme is not a SMTP server but Thunderbird will not let you configure an account without a SMTP server.
You can lie to Thunderbird by putting any existing SMTP server (like `smtp.gmail.com`) and choose "No Authentication" for the Authentication method field.*

A screenshot for reference:

![Thunderbird Account Creation Page filled with Aerogramme Quickstart configuration](/images/thunderbird-quickstart.png)

Clic "Done" (or "Re-test" then "Done) and your account should be configured:

![Overview of the mailbox list in Thunderbird](/images/thunderbird-quickstart-mbx.png)

As you can see, Thunderbird detected multiple mailboxes but they are all empty.
You can copy emails from your other mailbox to fill your Aerogramme one, test search, add/remove flags, and so on.
Mail reception will be emulated in the following section.

## Emulate the reception of an email

Remember, Aerogramme is about managing your mailbox, not managing mail transfer.
As this is an Aerogramme specific, the goal here is not to deploy Postfix, opensmtpd or any other MTA software.

Instead we will emulate their action: forwarding the messages they received to Aerogramme through the LMTP protocol.
Python natively supports the LMTP protocol: the following command uses Python to deliver a fake email:


```bash
python - <<EOF
from smtplib import LMTP
with LMTP("::1", port=1025) as lmtp:
    lmtp.set_debuglevel(2)
    lmtp.sendmail(
        "bob@example.tld",
        "alice@example.tld",
        "From: bob@example.tld\r\nTo: alice@example.tld\r\nSubject: Hello\r\n\r\nWorld\r\n",
    )
EOF
```

After running three times this script and clicking on 2 of these 3 emails on Thunderbird,
your mailbox should look like that:

![Overview of Thunderbird inbox](/images/thunderbird-quickstart-emails.png)

## That's all folks!

That's (already) the end of the quickstart section of Aerogramme.

You have learnt:
 - What Aerogramme does
 - How to download Aerogramme
 - How to run Aerogramme
 - How to connect Thunderbird to Aerogramme
 - How MTA are transferring emails to Aerogramme

If you are considering a real-world deployment now, you will
have many topics to consider, like integration with existing MTA, integration with a service manager, TLS encryption,
user management, auto-discovery, persistent storage, high-availability design, observability, backup, updates, etc.
All these points will be covered in the [Cookbook](@/documentation/cookbook/_index.md), it should be your next stop!

<!--
*Earlier, we started Aerogramme in the provider mode with a test account configured with the transparent flavor.*

-->