151 lines
4.4 KiB
Markdown
151 lines
4.4 KiB
Markdown
|
+++
|
||
|
title = "Quick Start"
|
||
|
weight = 0
|
||
|
sort_by = "weight"
|
||
|
template = "documentation.html"
|
||
|
+++
|
||
|
|
||
|
## Installation
|
||
|
|
||
|
Go to the download page and follow the instruction steps for your preferred installation method:
|
||
|
|
||
|
<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>
|
||
|
|
||
|
## Setup
|
||
|
|
||
|
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 \
|
||
|
--region garage \
|
||
|
--k2v-endpoint http://127.0.0.1:3904 \
|
||
|
--s3-endpoint http://127.0.0.1:3900 \
|
||
|
--aws-access-key-id GK... \
|
||
|
--aws-secret-access-key c0ffee... \
|
||
|
--bucket mailrage-me \
|
||
|
--user-secret s3cr3t
|
||
|
```
|
||
|
|
||
|
*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.*
|
||
|
|
||
|
|
||
|
The program will interactively ask you some questions and finally generates for you a snippet of configuration:
|
||
|
|
||
|
```
|
||
|
Please enter your password for key decryption.
|
||
|
If you are using LDAP login, this must be your LDAP password.
|
||
|
If you are using the static login provider, enter any password, and this will also become your password for local IMAP access.
|
||
|
Enter password:
|
||
|
Confirm password:
|
||
|
|
||
|
Cryptographic key setup is complete.
|
||
|
|
||
|
If you are using the static login provider, add the following section to your .toml configuration file:
|
||
|
|
||
|
[login_static.users.<username>]
|
||
|
password = "$argon2id$v=19$m=4096,t=3,p=1$..."
|
||
|
aws_access_key_id = "GK..."
|
||
|
aws_secret_access_key = "c0ffee..."
|
||
|
```
|
||
|
|
||
|
In this tutorial, we will use the static login provider (and not the LDAP one).
|
||
|
We will thus create a config file named `aerogramme.toml` in which we will paste the previous snippet. You also need to enter some other keys. In the end, your file should look like that:
|
||
|
|
||
|
```toml
|
||
|
s3_endpoint = "http://127.0.0.1:3900"
|
||
|
k2v_endpoint = "http://127.0.0.1:3904"
|
||
|
aws_region = "garage"
|
||
|
|
||
|
[lmtp]
|
||
|
bind_addr = "[::1]:12024"
|
||
|
hostname = "aerogramme.tld"
|
||
|
|
||
|
[imap]
|
||
|
bind_addr = "[::1]:1993"
|
||
|
|
||
|
[login_static]
|
||
|
default_bucket = "mailrage"
|
||
|
|
||
|
[login_static.users.me]
|
||
|
bucket = "mailrage-me"
|
||
|
user_secret = "s3cr3t"
|
||
|
email_addresses = [
|
||
|
"me@aerogramme.tld"
|
||
|
]
|
||
|
|
||
|
# copy pasted values from first-login
|
||
|
password = "$argon2id$v=19$m=4096,t=3,p=1$..."
|
||
|
aws_access_key_id = "GK..."
|
||
|
aws_secret_access_key = "c0ffee..."
|
||
|
```
|
||
|
|
||
|
If you fear to loose your password, you can backup your key with the following command:
|
||
|
|
||
|
```bash
|
||
|
aerogramme show-keys \
|
||
|
--region garage \
|
||
|
--k2v-endpoint http://127.0.0.1:3904 \
|
||
|
--s3-endpoint http://127.0.0.1:3900 \
|
||
|
--aws-access-key-id GK... \
|
||
|
--aws-secret-access-key c0ffee... \
|
||
|
--bucket mailrage-me \
|
||
|
--user-secret s3cr3t
|
||
|
```
|
||
|
|
||
|
You will then be asked for your key decryption password:
|
||
|
|
||
|
```
|
||
|
Enter key decryption password:
|
||
|
master_key = "..."
|
||
|
secret_key = "..."
|
||
|
```
|
||
|
|
||
|
## Launch
|
||
|
|
||
|
Start a server as follow:
|
||
|
|
||
|
```bash
|
||
|
aerogramme server
|
||
|
```
|
||
|
|
||
|
## Validate
|
||
|
|
||
|
Inject test emails:
|
||
|
|
||
|
```bash
|
||
|
./test/inject_emails.sh '<me@aerogramme.tld>' dxflrs
|
||
|
```
|
||
|
|
||
|
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](./mutt_mb.png)
|
||
|
|
||
|
And you can read them:
|
||
|
|
||
|
![Screenshot of mutt mail view](./mutt_mail.png)
|