diff --git a/content/documentation/cookbook/_index.md b/content/documentation/cookbook/_index.md index 9b32808..5f47046 100644 --- a/content/documentation/cookbook/_index.md +++ b/content/documentation/cookbook/_index.md @@ -5,4 +5,23 @@ sort_by = "weight" template = "documentation.html" +++ -*Not ready for production, nothing to see here...* +## Minimal deployment + - Static user management + - Single-node Garage storage + - TLS encryption + - Integration with a service manager + - SMTP server integration (MTA) + +## Standard deployment + - LDAP user management + - Garage cluster storage + - Integration in an orchestrator + - Auto-discovery + +## Lifecycle + - Updates + - Observability + - Backups + +## Hardened flavor + - Manual configuration diff --git a/content/documentation/quick-start/_index.md b/content/documentation/quick-start/_index.md index e090379..1783d3a 100644 --- a/content/documentation/quick-start/_index.md +++ b/content/documentation/quick-start/_index.md @@ -5,11 +5,30 @@ 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.* +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. -## Pull an image +*Enjoy your reading!* -Go to the download page, select a version and follow the instruction steps: +## 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. + + +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: -Do the same for [Garage](https://garagehq.deuxfleurs.fr/download/), as Aerogramme can't run without Garage. +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: -## Prepare your environment +```text +aerogramme 0.2.0 +Alex Auvolat , Quentin Dufour +A robust email server -Create a deployment folder: +USAGE: + aerogramme [OPTIONS] -```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.* +## Starting the daemon in development mode -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): +To start an in-memory daemon for evaluation purposes, you don't need any configuration file. Just run: ```bash -touch aerogramme.toml garage.toml +aerogramme --dev provider daemon ``` -*Do not forget to replace `{{TAG}}` by the tag you chose!* +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`. -## Setup Garage + + +## 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 this capability to deliver a fake email: -Create a basic configuration file for Garage: ```bash -cat > garage.toml <' 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) +--> diff --git a/static/images/thunderbird-quickstart-emails.png b/static/images/thunderbird-quickstart-emails.png new file mode 100644 index 0000000..5afb7dd Binary files /dev/null and b/static/images/thunderbird-quickstart-emails.png differ diff --git a/static/images/thunderbird-quickstart-mbx.png b/static/images/thunderbird-quickstart-mbx.png new file mode 100644 index 0000000..b010719 Binary files /dev/null and b/static/images/thunderbird-quickstart-mbx.png differ diff --git a/static/images/thunderbird-quickstart.png b/static/images/thunderbird-quickstart.png new file mode 100644 index 0000000..e1b723e Binary files /dev/null and b/static/images/thunderbird-quickstart.png differ