docs: restructure README to lead with Nix setup and improve flow
This commit is contained in:
Adriano Caloiaro
parent
4633758f0c
commit
b16f9f7095
1 changed files with 60 additions and 73 deletions
133
README.md
133
README.md
|
|
@ -2,50 +2,15 @@
|
|||
|
||||
Real-time mail delivery for maildirs via Fastmail's JMAP push API.
|
||||
|
||||
Connects to Fastmail's JMAP EventSource stream and delivers new messages directly to a local Maildir the moment they arrive without polling.
|
||||
Connects to Fastmail's JMAP EventSource stream and delivers new messages directly to a local Maildir the moment they arrive without polling. On first run, or when saved JMAP state is stale, mbrts falls back to `mbsync` for a full sync, then takes over from that point.
|
||||
|
||||
## How it works
|
||||
## Prerequisites
|
||||
|
||||
On first run, or when the saved JMAP state is stale, mbrts falls back to `mbsync` for a full sync, then takes over from that point.
|
||||
Create a Fastmail API token at **Settings → Security → API Tokens**. This is distinct from an IMAP app password — mbrts requires a proper JMAP bearer token.
|
||||
|
||||
## Setup
|
||||
|
||||
Create a Fastmail API token at **Settings → Security → API Tokens**.
|
||||
|
||||
### Config file
|
||||
|
||||
By default mbrts reads `$XDG_CONFIG_HOME/mbrts/config.yaml` (e.g. `~/.config/mbrts/config.yaml`):
|
||||
|
||||
```yaml
|
||||
accounts:
|
||||
- name: Personal
|
||||
maildir_path: /home/you/.mail/Personal
|
||||
password_command: "pass show fastmail/api-token"
|
||||
```
|
||||
|
||||
Each account requires exactly one token source:
|
||||
|
||||
| Field | Description |
|
||||
|---|---|
|
||||
| `password_command` | Shell command that prints the token to stdout |
|
||||
| `token_file` | Path to a file containing the token |
|
||||
| `token_env` | Name of an environment variable containing the token |
|
||||
|
||||
Optional fields: `mbsync_account` (mbsync channel/group name; defaults to `name`), `log_level` (top-level: `debug`, `info`, `warn`, `error`).
|
||||
|
||||
### CLI flags
|
||||
|
||||
Every config file option has an equivalent flag. Flags override the config file. A single account can be configured entirely on the command line without a config file:
|
||||
|
||||
```
|
||||
mbrts --name Personal \
|
||||
--maildir-path ~/.mail/Personal \
|
||||
--password-command "pass show fastmail/api-token"
|
||||
```
|
||||
|
||||
Run `mbrts --help` for the full flag list, or `mbrts --version` to print the version.
|
||||
|
||||
### Nix
|
||||
### Nix / home-manager
|
||||
|
||||
Add mbrts as a flake input:
|
||||
|
||||
|
|
@ -56,21 +21,11 @@ inputs.mbrts = {
|
|||
};
|
||||
```
|
||||
|
||||
The flake exposes:
|
||||
|
||||
| Output | Description |
|
||||
|---|---|
|
||||
| `packages.*.default` | The `mbrts` binary |
|
||||
| `overlays.default` | Adds `pkgs.mbrts` |
|
||||
| `homeManagerModules.default` | The `services.mbrts` home-manager module |
|
||||
|
||||
### home-manager module
|
||||
|
||||
Add the overlay and module to your home-manager configuration, then configure the service:
|
||||
Add the overlay and module, then configure the service:
|
||||
|
||||
```nix
|
||||
# in your flake outputs
|
||||
overlays = [ inputs.mbrts.overlays.default ];
|
||||
# in your flake overlays
|
||||
inputs.mbrts.overlays.default
|
||||
|
||||
# in your home-manager module list
|
||||
inputs.mbrts.homeManagerModules.default
|
||||
|
|
@ -88,24 +43,70 @@ services.mbrts = {
|
|||
};
|
||||
```
|
||||
|
||||
The module generates a config file and runs mbrts as a `systemd` user service. Logs are available via `journalctl --user -u mbrts -f`.
|
||||
The module generates a config file and runs mbrts as a systemd user service. Logs: `journalctl --user -u mbrts -f`.
|
||||
|
||||
Module options:
|
||||
**Module options:**
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `enable` | bool | — | Enable the service |
|
||||
| `package` | package | `pkgs.mbrts` | Package to use |
|
||||
| `logLevel` | enum | `"info"` | `debug`, `info`, `warn`, or `error` |
|
||||
| `accounts` | list | `[]` | List of account submodules (see config file fields above) |
|
||||
| `accounts` | list | `[]` | List of account submodules (see fields below) |
|
||||
|
||||
**Account fields** (each account requires exactly one token source):
|
||||
|
||||
| Field | Description |
|
||||
|---|---|
|
||||
| `name` | Account name; used for state file and default mbsync channel |
|
||||
| `maildirPath` | Path to the local Maildir root |
|
||||
| `passwordCommand` | Shell command that prints the bearer token to stdout |
|
||||
| `tokenFile` | Path to a file containing the bearer token |
|
||||
| `tokenEnv` | Environment variable containing the bearer token |
|
||||
| `mbsyncAccount` | mbsync channel/group name for fallback (defaults to `name`) |
|
||||
|
||||
### Standalone
|
||||
|
||||
Build the binary:
|
||||
|
||||
```
|
||||
CGO_ENABLED=0 go build -o mbrts .
|
||||
```
|
||||
|
||||
By default mbrts reads `$XDG_CONFIG_HOME/mbrts/config.yaml` (e.g. `~/.config/mbrts/config.yaml`):
|
||||
|
||||
```yaml
|
||||
accounts:
|
||||
- name: Personal
|
||||
maildir_path: /home/you/.mail/Personal
|
||||
password_command: "pass show fastmail/api-token"
|
||||
```
|
||||
|
||||
Every config file option has an equivalent CLI flag, and flags override the config file. A single account can be configured entirely on the command line:
|
||||
|
||||
```
|
||||
mbrts --name Personal \
|
||||
--maildir-path ~/.mail/Personal \
|
||||
--password-command "pass show fastmail/api-token"
|
||||
```
|
||||
|
||||
Run `mbrts --help` for the full flag list, or `mbrts --version` to print the version.
|
||||
|
||||
## aerc
|
||||
|
||||
Configure the account source as `maildir://` so aerc picks up delivered messages immediately via inotify:
|
||||
|
||||
```ini
|
||||
source = maildir:///home/you/.mail/Personal
|
||||
```
|
||||
|
||||
## Using mbrts alongside mbsync
|
||||
|
||||
mbrts handles inbound delivery; mbsync is still useful for pushing local changes (read flags, deletions, moves) back to Fastmail. They can coexist, but need careful configuration to avoid duplicate messages.
|
||||
mbrts handles inbound delivery; mbsync is still useful for pushing local changes (read flags, deletions, moves) back to Fastmail. They can coexist, but require careful configuration to avoid duplicate messages.
|
||||
|
||||
The problem is that mbsync tracks synced messages by IMAP UID in its own state database. It knows nothing about messages mbrts delivered directly to the Maildir. Because of this blindness to mbrts, mbsync re-downloads messages that mbrts has already written, creating duplicates.
|
||||
**The problem:** mbsync tracks synced messages by IMAP UID in its own state database. It knows nothing about messages mbrts delivered directly to the Maildir. Because of this, mbsync re-downloads messages that mbrts has already written, creating duplicates.
|
||||
|
||||
The fix is to give mbsync two separate channels per account; one for the scheduled sync (flags and deletions only, no new messages), and one for mbrts to call on-demand as a fallback when its JMAP state is missing or stale.
|
||||
**The fix:** give mbsync two separate channels per account — one for the scheduled sync (flags and deletions only), and one for mbrts to call on-demand as a fallback when its JMAP state is missing or stale.
|
||||
|
||||
```
|
||||
# scheduled channel — only pushes local changes upstream
|
||||
|
|
@ -131,7 +132,7 @@ accounts:
|
|||
mbsync_account: Personal-pull
|
||||
```
|
||||
|
||||
Any scheduled mbsync timers then runs `mbsync Personal` (flags/deletions only), while mbrts calls `mbsync Personal-pull` on fallback (new messages only).
|
||||
Any scheduled mbsync timer then runs `mbsync Personal` (flags/deletions only), while mbrts calls `mbsync Personal-pull` on fallback (new messages only).
|
||||
|
||||
### With home-manager
|
||||
|
||||
|
|
@ -165,17 +166,3 @@ services.mbrts.accounts = [
|
|||
}
|
||||
];
|
||||
```
|
||||
|
||||
## Build
|
||||
|
||||
```
|
||||
CGO_ENABLED=0 go build -o mbrts .
|
||||
```
|
||||
|
||||
## aerc
|
||||
|
||||
Configure the account source as `maildir://` so aerc picks up delivered messages immediately via inotify:
|
||||
|
||||
```ini
|
||||
source = maildir:///home/you/.mail/Personal
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue