WIP doc

content/documentation/cookbook/key_backup.txt

@@ -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 = "..."
+```
+
+

content/documentation/cookbook/ldap.txt

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

content/documentation/cookbook/lmtp.txt

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

content/documentation/development/netcat.md

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

content/documentation/quick-start/_index.md

@@ -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 \
+aerogramme first-login --static alice
-  --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.
+Append the following section to your .toml configuration file:
-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.
+[login_static.users.alice]
-
-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..."
+user_secret = "..."
-aws_secret_access_key = "c0ffee..."
 ```
 
-In this tutorial, we will use the static login provider (and not the LDAP one).
+*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.*
-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
+Restart the server to load the new configuration:
-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 \
+docker compose up -d --force-recreate aerogramme
-  --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
 
+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:
 

content/documentation/reference/config.md

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