210 lines
5.6 KiB
Markdown
210 lines
5.6 KiB
Markdown
+++
|
|
title = "Quick Start"
|
|
weight = 0
|
|
sort_by = "weight"
|
|
template = "documentation.html"
|
|
+++
|
|
|
|
*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.*
|
|
|
|
## Pull an image
|
|
|
|
Go to the download page, select a version and follow the instruction steps:
|
|
|
|
<a
|
|
href="/download/"
|
|
title="Aerogramme releases"
|
|
class="group flex items-center justify-center space-x-1 font-semibold shadow hover:shadow hover:border-none border-none px-2 py-1.5 rounded text-white transition-all duration-500 bg-gradient-to-tl from-aerogramme-blue via-blue-500 to-blue-300 bg-size-200 bg-pos-0 hover:bg-pos-100">
|
|
<svg class="w-6 h-6 animate-pulse text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M9 19l3 3m0 0l3-3m-3 3V10"></path></svg>
|
|
<span class="hidden md:inline text-white">Download</span>
|
|
</a>
|
|
|
|
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 --static alice
|
|
```
|
|
|
|
The program will interactively ask you some questions and finally generates for you a snippet of configuration:
|
|
|
|
```
|
|
Append the following section to your .toml configuration file:
|
|
|
|
[login_static.users.alice]
|
|
password = "$argon2id$v=19$m=4096,t=3,p=1$..."
|
|
user_secret = "..."
|
|
```
|
|
|
|
*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.*
|
|
|
|
Restart the server to load the new configuration:
|
|
|
|
```bash
|
|
docker compose up -d --force-recreate aerogramme
|
|
```
|
|
|
|
## 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:
|
|
|
|
```ini
|
|
set imap_user = quentin
|
|
set imap_pass = p455w0rd
|
|
set folder = imap://localhost:1993
|
|
set spoolfile = +INBOX
|
|
set ssl_starttls = no
|
|
set ssl_force_tls = no
|
|
mailboxes = +INBOX
|
|
bind index G imap-fetch-mail
|
|
```
|
|
|
|
And then simply launch `mutt`.
|
|
The first time nothing will happen as Aerogramme must
|
|
process your incoming emails. Just ask `mutt` to refresh its
|
|
view by pressing `G` (for *Get*).
|
|
|
|
Now, you should see some emails:
|
|
|
|
|
|
|
|
And you can read them:
|
|
|
|
|