Start filling the cookbook
This commit is contained in:
parent
9063b77e19
commit
5b78e13b1e
GPG Key ID:
E9602264D639FF68
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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*
|
||||
|
|
|
|||
Loading…
Reference in New Issue