Start filling the cookbook

This commit is contained in:
Quentin 2024-01-23 12:08:50 +01:00
parent 9063b77e19
commit 5b78e13b1e
Signed by: quentin
GPG key ID: E9602264D639FF68
5 changed files with 199 additions and 11 deletions

View file

@ -16,9 +16,9 @@ However, as Aerogramme is a distributed-first server,
you will not benefit from all of its nice properties, and many manual you will not benefit from all of its nice properties, and many manual
work will be required. work will be required.
- [Local storage](@/documentation/cookbook/single-node-garage-storage.md)
- [Configuration file](@/documentation/cookbook/config.md) - [Configuration file](@/documentation/cookbook/config.md)
- [User management](@/documentation/cookbook/static-user-management.md) - [User management](@/documentation/cookbook/static-user-management.md)
- [Local storage](@/documentation/cookbook/single-node-garage-storage.md)
- [TLS encryption](@/documentation/cookbook/tls-encryption.md) - [TLS encryption](@/documentation/cookbook/tls-encryption.md)
- [Integration with a service manager](@/documentation/cookbook/service-manager.md) (systemd or docker) - [Integration with a service manager](@/documentation/cookbook/service-manager.md) (systemd or docker)
- [SMTP server integration](@/documentation/cookbook/smtp-server.md) (MTA) - [SMTP server integration](@/documentation/cookbook/smtp-server.md) (MTA)

View file

@ -1,13 +1,12 @@
+++ +++
title = "Configuration file" title = "Configuration file"
weight = 5 weight = 10
+++ +++
In the [quickstart](@/documentation/quick-start/_index.md), you launched Aerogramme in "development mode", that do not require a configuration file. But for a real-world usage, you will need to specificy many things: how your users are managed, which port to use, how and where data is stored, etc. In the [quickstart](@/documentation/quick-start/_index.md), you launched Aerogramme in "development mode", that do not require a configuration file. But for a real-world usage, you will need to specificy many things: how your users are managed, which port to use, how and where data is stored, etc.
## A first configuration file This page describes how to write your first configuration file.
If you want a complete reference, check the dedicated [Configuration Reference](@/documentation/reference/config.md) page.
Let's start with the following configuration file:
```toml ```toml
role = "Provider" role = "Provider"

View file

@ -3,4 +3,84 @@ title = "Service Managers (eg. systemd)"
weight = 40 weight = 40
+++ +++
Todo You may want to start Aerogramme on boot.
## systemd
We make some assumptions for this systemd deployment.
- Your garage binary is located at `/usr/local/bin/aerogramme`.
- Your configuration file is located at `/etc/aerogramme/config.toml`.
- If you use Aerogramme's user management, the user list is set to `/etc/aerogramme/users.toml`.
Create a file named `/etc/systemd/system/aerogramme.service`:
```ini
[Unit]
Description=Aerogramme Email Server
After=network-online.target
Wants=network-online.target
[Service]
Environment='RUST_LOG=aerogramme=info' 'RUST_BACKTRACE=1'
ExecStart=/usr/local/bin/aerogramme -c /etc/aerogramme/config.toml provider daemon
DynamicUser=true
ProtectHome=true
NoNewPrivileges=true
[Install]
WantedBy=multi-user.target
```
**A note on hardening:** The Aerogramme daemon is not expected to write on the filesystem.
When you use the `aerogramme provider account`, the write is done by your current user/process,
not the daemon process. That's why we don't define a `StateDirectory`.
To start the service then automatically enable it at boot:
```bash
sudo systemctl start aerogramme
sudo systemctl enable aerogramme
```
To see if the service is running and to browse its logs:
```bash
sudo systemctl status aerogramme
sudo journalctl -u aerogramme
```
To add a new user:
```bash
sudo aerogramme \
-c /etc/aerogramme/config.toml \
provider account add --login alice --setup #...
sudo systemctl reload aerogramme
```
## docker-compose
An example docker compose deployment with Garage included:
```yml
version: "3"
services:
aerogramme:
image: registry.deuxfleurs.org/aerogramme:0.2.0
restart: unless-stopped
ports:
- "1025:1025"
- "143:1143"
volumes:
- aerogramme.toml:/aerogramme.toml
- users.toml:/users.toml
garage:
image: docker.io/dxflrs/garage:v0.9.1
restart: unless-stopped
volumes:
- garage.toml:/etc/garage.toml
- garage-meta:/var/lib/garage/meta
- garage-data:/var/lib/garage/data
```

View file

@ -1,7 +1,52 @@
+++ +++
title = "Local storage" title = "Local storage"
weight = 20 weight = 5
+++ +++
Todo Currently, Aerogramme does not support local storage (ie. storing emails
on your filesystem directly). It might support this feature in the future,
but no ETA is announced yet. In the mean time, we will deploy a single-node
Garage cluster to store the data.
Start by following the [Garage Quickstart](https://garagehq.deuxfleurs.fr/documentation/quick-start/) up to "Creating a cluster layout" (included).
## Setup your storage
Create one key per user:
```bash
garage key create aerogramme
# ...
```
*Do not forget to note the key, it will be needed later.*
Create an Aerogramme bucket for each user:
```bash
garage bucket create aerogramme-alice
garage bucket create aerogramme-bob
garage bucket create aerogramme-charlie
# ...
```
*Having one bucket per user is an opinionated design choice made to support Aerogramme [Per-user storage, per-user encryption](@/documentation/design/per-user-encryption.md) goal.*
And then allow the aerogramme key on each bucket:
```bash
garage bucket allow --read --write --key aerogramme aerogramme-alice
garage bucket allow --read --write --key aerogramme aerogramme-bob
garage bucket allow --read --write --key aerogramme aerogramme-charlie
# ...
```
## Automating it
You can automate this by using the [Garage Admin API](https://garagehq.deuxfleurs.fr/documentation/reference-manual/admin-api/) and the [S3 API](https://garagehq.deuxfleurs.fr/documentation/reference-manual/s3-compatibility/).
## Quota
You can use Garage per-bucket quota to limit the amount of space a user can
use, but such data is not reported on the IMAP side.

View file

@ -1,6 +1,70 @@
+++ +++
title = "User Management" title = "User Management"
weight = 10 weight = 20
+++ +++
Aerogramme can externalize its user management through [LDAP](@/documentation/cookbook/ldap.md), but if you target a simple deployment, it has also an internal user management system that will be covered here. Aerogramme can externalize its user management through [LDAP](@/documentation/cookbook/ldap.md), but if you target a simple deployment, it has also an internal user management system that will be covered here.
As a pre-requisite, you must have your `aerogramme.toml` file configured for "Static" user management as described in [Configuration file](@/documentation/cookbook/config.md). You also need a configured Garage instance, either [local](@/documentation/cookbook/single-node-garage-storage.md) or [distributed](@/documentation/cookbook/garage-cluster-storage.md).
## Adding users
Once you have done all the previous pre-requisites, Aerogramme provides a command-line utility to add a user:
```bash
aerogramme provider account add --login alice --setup <(cat <<EOF
email_addresses = [ "alice@example.tld", "alice.smith@example.tld" ]
clear_password = "hunter2"
storage_driver = "Garage"
s3_endpoint = "http://localhost:3900"
k2v_endpoint = "http://localhost:3904"
aws_region = "garage"
aws_access_key_id = "GKa8..."
aws_secret_access_key = "7ba95..."
bucket = "aerogramme-alice"
EOF
)
aerogramme provider account add --login bob --setup # ...
# ...
aerogramme provider account add --login charlie --setup # ...
# ...
```
*You must run this command for all your users.*
If you don't set the `clear_password` field, it will be interactively asked.
This command will edit your `user_list` file. If your Aerogramme daemon is already running, you must reload it in order to load the newly added users. To reload Aerogramme, run:
```bash
aerogramme provider reload
```
## Change account password
You might need to change an account password, you can run:
```bash
aerogramme provider account change-password --login alice
```
You can pass the old and new password through environment variables:
```bash
AEROGRAMME_OLD_PASSWORD=x \
AEROGRAMME_NEW_PASSWORD=y \
aerogramme provider account change-password --login alice
```
*Do not forget to reload*
## Delete account
```bash
aerogramme provider account delete --login alice
```
*Do not forget to reload*