Deuxfleurs/aerogramme.deuxfleurs.fr
17
0
Fork 0
Code Pull requests Activity

WIP doc

Browse source
This commit is contained in:
Quentin 2023-06-02 17:29:36 +02:00
parent ebee1ae3eb
commit 7480308889
Signed by: quentin
GPG key ID: E9602264D639FF68
6 changed files with 181 additions and 91 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
content/documentation/cookbook/key_backup.txt Normal file
View file

@ -0,0 +1,22 @@
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 aerogramme \
--user-secret s3cr3t
```
You will then be asked for your key decryption password:
```
Enter key decryption password:
master_key = "..."
secret_key = "..."
```

5
content/documentation/cookbook/ldap.txt Normal file
View file

@ -0,0 +1,5 @@
ldap
bottin
other ldap servers

3
content/documentation/cookbook/lmtp.txt Normal file
View file

@ -0,0 +1,3 @@
lmtp
postfix
other smtp servers

2
content/documentation/development/netcat.md
View file

@ -1,5 +1,5 @@
+++
title = "netcat"
title = "Debug with netcat"
weight = 10
+++

222
content/documentation/quick-start/_index.md
View file

@ -5,9 +5,11 @@ sort_by = "weight"
template = "documentation.html"
+++
## Installation
*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.*
Go to the download page and follow the instruction steps for your preferred installation method:
## Pull an image
Go to the download page, select a version and follow the instruction steps:
<a
href="/download/"
@ -17,111 +19,169 @@ class="group flex items-center justify-center space-x-1 font-semibold shadow hov
<span class="hidden md:inline text-white">Download</span>
</a>
## Setup
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 garage -ti /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 = "http://garage:3900" # use docker addressing
k2v_endpoint = "http://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 \
--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
aerogramme first-login --static alice
```
*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:
Append the following section to your .toml configuration file:
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>]
[login_static.users.alice]
password = "$argon2id$v=19$m=4096,t=3,p=1$..."
aws_access_key_id = "GK..."
aws_secret_access_key = "c0ffee..."
user_secret = "..."
```
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:
*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.*
```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:
Restart the server to load the new configuration:
```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
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:

18
content/documentation/reference/config.md
View file

@ -3,7 +3,7 @@ title = "Configuration"
weight = 10
+++
# Configuration file
## Sample
A configuration file that illustrate all the possible options,
in practise, many fields are omitted:
@ -23,9 +23,9 @@ bind_addr = "[::1]:993"
[login_static]
default_bucket = "aerogramme"
[login_static.user.alan]
[login_static.users.alan]
email_addresses = [
"alan@smith.me"
"alan@smith.me",
"aln@example.com"
]
password = "$argon2id$v=19$m=4096,t=3,p=1$..."
@ -35,7 +35,7 @@ aws_secret_access_key = "c0ffee"
bucket = "aerogramme-alan"
user_secret = "s3cr3t"
alternate_user_secrets = [ "s3cr3t2" "s3cr3t3" ]
alternate_user_secrets = [ "s3cr3t2", "s3cr3t3" ]
master_key = "..."
secret_key = "..."
@ -61,7 +61,7 @@ bucket_attr = "bucket"
```
## Global configuration options
## Global configuration details
### `s3_endpoint`
@ -69,17 +69,17 @@ bucket_attr = "bucket"
### `aws_region`
## LMTP configuration options
## LMTP configuration details
### `lmtp.bind_addr`
### `lmtp.hostname`
## IMAP configuration options
## IMAP configuration details
### `imap.bind_addr`
## Static login configuration options
## Static login configuration details
### `login_static.default_bucket`
@ -99,7 +99,7 @@ bucket_attr = "bucket"
### `login_static.user.<name>.secret_key`
## LDAP login configuration options
## LDAP login configuration details
### `login_ldap.ldap_server`