Start filling the cookbook

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)

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
+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
 role = "Provider"

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
+```

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.

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 <<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*