182 lines
7.8 KiB
Markdown
182 lines
7.8 KiB
Markdown
+++
|
|
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>
|
|
|
|
...
|
|
```
|
|
|
|
If you use Docker, you can get the same result with:
|
|
|
|
```bash
|
|
docker run --network host dxflrs/aerogramme:0.2.0 aerogramme
|
|
```
|
|
|
|
*Using host network is not required for this example, but it will be useful for the following,
|
|
as, by default, Aerogramme often binds on localhost, and thus its sockets are not available
|
|
outside of the container even if you bind the correct ports.*
|
|
|
|
## 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
|
|
```
|
|
|
|
If you use the docker container, you must launch:
|
|
|
|
```bash
|
|
docker run --network host dxflrs/aerogramme:0.2.0 aerogramme --dev provider daemon
|
|
```
|
|
|
|
*Starting from now, docker commands will not be given anymore. We assume that you have understood the pattern
|
|
on how to map the documentation commands to Docker.*
|
|
|
|
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:
|
|
|
|
|
|
|
|
Clic "Done" (or "Re-test" then "Done) and your account should be configured:
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
## 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.*
|
|
|
|
-->
|