diff --git a/content/documentation/cookbook/_index.md b/content/documentation/cookbook/_index.md index 2645e84..58deed2 100644 --- a/content/documentation/cookbook/_index.md +++ b/content/documentation/cookbook/_index.md @@ -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 work will be required. + - [Local storage](@/documentation/cookbook/single-node-garage-storage.md) - [Configuration file](@/documentation/cookbook/config.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) - [Integration with a service manager](@/documentation/cookbook/service-manager.md) (systemd or docker) - [SMTP server integration](@/documentation/cookbook/smtp-server.md) (MTA) diff --git a/content/documentation/cookbook/config.md b/content/documentation/cookbook/config.md index f2c85ed..e4ac3de 100644 --- a/content/documentation/cookbook/config.md +++ b/content/documentation/cookbook/config.md @@ -1,13 +1,12 @@ +++ 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 - -Let's start with the following 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. ```toml role = "Provider" diff --git a/content/documentation/cookbook/service-manager.md b/content/documentation/cookbook/service-manager.md index 1962966..2c5ea7a 100644 --- a/content/documentation/cookbook/service-manager.md +++ b/content/documentation/cookbook/service-manager.md @@ -3,4 +3,84 @@ title = "Service Managers (eg. systemd)" 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 +``` diff --git a/content/documentation/cookbook/single-node-garage-storage.md b/content/documentation/cookbook/single-node-garage-storage.md index 09a9561..4514b5d 100644 --- a/content/documentation/cookbook/single-node-garage-storage.md +++ b/content/documentation/cookbook/single-node-garage-storage.md @@ -1,7 +1,52 @@ +++ 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. diff --git a/content/documentation/cookbook/static-user-management.md b/content/documentation/cookbook/static-user-management.md index cc7357b..f84c342 100644 --- a/content/documentation/cookbook/static-user-management.md +++ b/content/documentation/cookbook/static-user-management.md @@ -1,6 +1,70 @@ +++ 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 <