> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oximail.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Premier démarrage et assistant de configuration

> Lancez l'assistant oximail setup pour créer la première organisation, le compte administrateur, la clé DKIM, le fichier de configuration et le service systemd, puis vérifiez que le serveur fonctionne.

Une fois le [binaire installé](./installation), `oximail setup` met le serveur
en route. L'assistant génère la configuration, la clé DKIM, la première organisation
et le compte administrateur, écrit une unité systemd, démarre le service et le
vérifie. L'assistant est le chemin recommandé pour un premier démarrage. Chaque
action peut aussi être lancée comme sous-commande distincte pour les
déploiements automatisés.

<Note>
  Cette page décrit ce que fait réellement l'assistant dans OxiMail v0.30.0,
  étape par étape, dans l'ordre d'exécution. Lorsqu'une étape est conditionnelle
  ou facultative, c'est précisé. Les étapes que l'assistant ne fait pas sont
  listées à la fin.
</Note>

## Lancer l'assistant

```bash theme={null}
oximail setup
```

Par défaut, l'assistant lit et écrit la configuration du serveur dans
`/etc/oximail/oximail.toml`. Il doit ouvrir des ports privilégiés et écrire dans
`/etc/oximail` et `/var/lib/oximail`. Lancez-le donc en tant que root.

Options :

| Option                   | Effet                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| `--config <chemin>`      | Chemin du TOML serveur. Par défaut `/etc/oximail/oximail.toml`.                                  |
| `--config-file <chemin>` | Mode **non interactif** à partir d'un fichier TOML de setup (sans question).                     |
| `--dry-run`              | Affiche ce qui serait fait et la configuration générée, sans rien écrire ni démarrer le service. |

Si `/etc/oximail/oximail.toml` existe déjà, l'assistant prévient et demande s'il
faut l'écraser. Si vous refusez, le setup est annulé et la configuration
existante est conservée.

## Déroulé interactif (serveur principal)

L'assistant pose quelques questions, puis exécute les étapes ci-dessous dans
l'ordre.

### Questions posées au départ

1. **Domaine de messagerie principal** (par exemple `oximail.ch`), c'est-à-dire
   la partie domaine de vos adresses.
2. **Nom d'hôte du serveur de messagerie** (par défaut `mail.<domaine>`).
3. **Mode de déploiement** : `Primary mail server` (serveur principal),
   `Backup MX` (MX secondaire) ou `Smarthost relay (dedicated hub)` (hub de
   relais dédié). Le MX secondaire et le hub smarthost ont chacun leur propre
   déroulé, décrit plus bas.
4. **Topologie de déploiement** : `Direct` (OxiMail gère le TLS sur le port 443)
   ou `Behind reverse proxy` (derrière un proxy inverse comme Caddy ou Nginx).
   L'option proxy demande aussi le port HTTP local sur lequel OxiMail doit
   écouter (par défaut `8080`).
5. **Mode d'envoi sortant** : `Direct` ou `Par un relais`. L'assistant sonde le
   port 25 sortant et recommande le relais quand la remise directe est
   impossible (la plupart des clouds bloquent ce port). Voir
   [Relais sortant & smarthost](./operator/outbound-relay) pour tout le
   parcours relais, y compris le préflight de sortie pour repasser en direct
   plus tard. Cette question concerne le côté **leaf** (envoyer *via* un
   relais) ; elle est sautée sur le déroulé hub smarthost, les deux bouts d'un
   relais ne se confondant jamais.

### Étape : vérification des ports

L'assistant tente d'ouvrir chaque port requis en local et affiche `OK` ou `FAIL`
avec la raison (permission refusée, port déjà utilisé, ouverture impossible).
Les ports requis sont :

| Port | Usage                                |
| ---- | ------------------------------------ |
| 25   | SMTP entrant (réception du courrier) |
| 80   | HTTP (challenges de certificat ACME) |
| 443  | HTTPS / JMAP                         |
| 465  | SMTPS (soumission chiffrée)          |
| 587  | Soumission SMTP (envoi du courrier)  |
| 993  | IMAPS (lecture du courrier)          |

Si vous avez choisi le proxy inverse, les ports 80 et 443 sont ignorés (le proxy
les gère). Des ports bloqués n'arrêtent pas l'assistant, mais le serveur peut ne
pas fonctionner tant qu'ils ne sont pas ouverts dans votre pare-feu.

### Étape : répertoires de données

L'assistant crée `/var/lib/oximail`, `/var/lib/oximail/blobs`, `/etc/oximail`,
`/etc/oximail/dkim` et `/etc/oximail/tls`. Il n'y a pas de `/var/log/oximail` :
les journaux partent sur la sortie standard et sont captés par journald.

### Étape : DNS

L'assistant demande un **jeton d'API Cloudflare** (laissez vide pour configurer
le DNS à la main). Il détecte votre IP publique automatiquement (et vous demande
de la saisir si la détection échoue), puis contrôle les enregistrements DNS du
domaine et affiche un rapport réussite/échec.

* **Avec un jeton**, il peut créer les enregistrements manquants via l'API
  Cloudflare : A, MX (priorité 10), SPF, DMARC, MTA-STS (TXT et CNAME), TLS-RPT,
  les CNAME autoconfig et autodiscover, un enregistrement CAA qui limite
  l'émission de certificats à Let's Encrypt, et des enregistrements SRV pour
  l'autoconfiguration des clients (`_autodiscover`, `_imaps`, `_submission`,
  `_caldavs`, `_carddavs`). Si un enregistrement MX en conflit existe, il
  demande avant de le remplacer. Il revérifie ensuite le DNS.
* **Sans jeton**, il affiche les résultats du contrôle et vous indique de créer
  les enregistrements vous-même.

### Étape : DKIM

L'assistant génère une paire de clés DKIM RSA (sélecteur `default`) dans
`/etc/oximail/dkim/<domaine>.default.key` et affiche l'enregistrement DNS à
publier. Si un jeton Cloudflare a été fourni, il publie aussi l'enregistrement
TXT DKIM sur `default._domainkey.<domaine>` (en supprimant d'abord tout
enregistrement obsolète pour ce sélecteur). La clé publiée est au format SPKI
(`v=DKIM1; k=rsa; p=...`).

<Note>
  La publication DKIM via Cloudflare n'a lieu qu'à l'intérieur de l'assistant
  complet. Les domaines ajoutés plus tard, ou les installations sans jeton
  Cloudflare, n'ont aucun enregistrement TXT DKIM publié automatiquement.
  Générez et publiez ces enregistrements à la main (voir la section
  Génération de clé DKIM plus bas).
</Note>

### Étape : fichier de configuration

L'assistant demande l'**adresse de l'administrateur** (par défaut
`admin@<domaine>`) et, pour un déploiement direct, l'**adresse ACME (Let's
Encrypt)** (par défaut l'adresse de l'administrateur). Derrière un proxy inverse,
ACME est ignoré car le proxy gère le TLS.

L'assistant écrit `/etc/oximail/oximail.toml` pour un serveur principal. Contenu
principal :

* `[server]` : nom d'hôte, URL de base, adresses d'écoute (direct : `0.0.0.0:443`
  et `0.0.0.0:80` ; proxy : `127.0.0.1:<port>` avec `trusted_proxies`).
* `[storage]` : SQLite dans `/var/lib/oximail/data.db`, blobs dans
  `/var/lib/oximail/blobs`, `encrypted = true`.
* `[auth] default_tenant = "default"`.
* `[mode] role = "primary"`.
* `[smtp]` : ports d'écoute et un bloc `[[smtp.dkim_keys]]` pour le couple
  domaine/sélecteur.
* `[tls]` : ACME activé (direct) ou désactivé (proxy).
* `[legacy]` : IMAP, CalDAV et CardDAV activés.
* `[spam]`, `[security]` (fail2ban et IP de confiance),
  `[rate_limit]`, `[network] contribute` et `[logging]` (JSON vers journald).

Pour un déploiement derrière un proxy inverse, l'assistant affiche un extrait de
Caddyfile prêt à l'emploi et précise que les ports SMTP (25, 587, 465) et IMAP
(993) écoutent en direct et ne passent pas par le proxy. L'extrait fait passer
**tout** le trafic vers OxiMail, à la seule exception du chemin de défi HTTP
d'ACME. Une liste blanche de routes est volontairement écartée : une famille de
routes oubliée casse en silence la découverte des clients ou le DAV. Quand le
webmail est servi depuis une autre origine, l'assistant remplit aussi
`[server] allowed_origins` ; le CORS est traité par OxiMail lui-même, jamais
par le proxy (une interception globale des `OPTIONS` au proxy casse en silence
la découverte des clients DAV). Pour ajuster ces valeurs ensuite, voir
[Configuration](./operator/configuration).

### Étape : unité systemd

L'assistant écrit `/etc/systemd/system/oximail.service`. L'unité lance
`oximail serve --config /etc/oximail/oximail.toml`, redémarre en cas d'échec,
relève la limite de descripteurs de fichiers et envoie la sortie vers journald
sous l'identifiant `oximail`. S'il ne peut pas écrire le fichier (pas root), il
affiche le contenu de l'unité pour que vous l'installiez à la main. Voir
[Installation](./installation) pour le détail de l'unité.

### Étape : organisation et compte administrateur

L'assistant crée la première organisation (un *tenant* au sens du stockage : id
`default`, nom `Default`, domaine déduit de l'adresse de l'administrateur), puis
le compte administrateur. La création est idempotente : si elle existe déjà,
l'assistant le signale et continue.

Le **mot de passe administrateur** est demandé, avec confirmation. Il doit faire
au moins 8 caractères et contenir une majuscule, une minuscule et un chiffre ;
la saisie se répète tant que le mot de passe est trop faible. Le compte est créé
avec le rôle `admin` et la langue `fr`.

L'assistant capture aussi le **fuseau horaire par défaut** de l'organisation
(un nom IANA, avec pour défaut le fuseau du système hôte : le cas courant est
une simple touche Entrée). C'est le dernier étage de la chaîne de repli du
calendrier (fuseau de l'événement → fuseau de l'utilisateur → fuseau de
l'organisation → UTC) : les événements flottants se résolvent en heure locale
plutôt qu'en UTC. Un fuseau inconnu n'est jamais persisté, il retombe sur la
détection. Modifiable ensuite avec `oximail tenant update --default-timezone`.

<Warning>
  Tant qu'aucune organisation n'existe, le serveur démarre en mode assistant web ("no
  tenants"). L'assistant en ligne de commande crée toujours le tenant `default`
  avant le compte administrateur, donc un `oximail setup` terminé vous permet de
  vous connecter directement.
</Warning>

### Étape : démarrage du service

L'assistant exécute `systemctl daemon-reload`, `systemctl enable oximail` et
`systemctl start oximail`, puis interroge le port 443 pendant 90 secondes au
maximum, le temps que le certificat ACME soit provisionné. Il indique si le
serveur est devenu disponible et, sinon, vous renvoie vers
`journalctl -u oximail -f`.

### Étape : vérification

Il se connecte aux ports 25, 587, 993 et 443, contrôle le point d'accès JMAP sur
`https://<nom-d-hote>/.well-known/jmap` (un code 401 compte comme disponible) et
confirme la présence du répertoire DKIM et du fichier de configuration.

En cas de réussite, l'assistant affiche l'URL de connexion
(`https://<nom-d-hote>/auth/login`), le chemin de la configuration et la commande
de consultation des journaux.

### Étape : import facultatif de données

Enfin, l'assistant propose d'importer du courrier existant. Choix possibles :
**Skip** (ignorer), **From IMAP server** (Dovecot, Exchange, Gmail, tout serveur
IMAP4), **From Stalwart (JMAP API)** ou **From mbox/Maildir files**. Chaque choix
demande les informations de connexion correspondantes. Cette étape a lieu
**après** que le serveur est déjà configuré et démarré, donc un import en échec
ne casse pas l'installation. Vous pouvez réessayer à tout moment avec
`oximail migrate`. Voir [Migration](./operator/migration) pour le flux d'import
autonome.

## Déroulé MX secondaire

Si vous choisissez **Backup MX** comme mode de déploiement, l'assistant lance un
déroulé dédié. Il demande le nom d'hôte du MX principal (par défaut
`mail.<domaine>`), les domaines de relais supplémentaires et le mode de
transfert (`queue` pour accepter en local et réessayer vers le principal, avec
rapports DSN en cas de rejet définitif ; ou `proxy` pour relayer en temps réel
et propager la réponse du principal, avec repli sur `queue` si le principal est
injoignable). Il crée ensuite le compte administrateur, génère le DKIM, écrit une
configuration `role = "backup"`, installe l'unité systemd, crée éventuellement
les enregistrements DNS de secours (MX priorité 20, A, DKIM et SRV
IMAP/soumission via Cloudflare), et vérifie le port 25 et la configuration.

## Déroulé smarthost

Si vous choisissez **Smarthost relay (dedicated hub)**, l'assistant exécute le
**même déroulé que le serveur principal** avec des ajustements ciblés : un
smarthost est un MTA sortant complet, pas un mode d'installation séparé (il n'y
a délibérément aucun chemin de démarrage dédié). Ce qui change :

* L'assistant demande la ou les **IP d'egress** du hub (séparées par des
  virgules). Seuls des littéraux IP sont acceptés : ils alimentent
  l'auto-surveillance DNSBL et l'enregistrement SPF publié, où un nom d'hôte ou
  une faute de frappe casserait silencieusement le SPF de tous les clients.
* La configuration générée déclare `profile = "smarthost"` sous `[mode]`. Le
  profil est une **déclaration auditée, jamais un commutateur de
  comportement** : à chaque démarrage, le serveur la compare à la configuration
  et avertit (via un signal d'audit de démarrage que votre supervision peut
  alerter) si les surfaces boîtes aux lettres sont encore actives ou si
  l'auto-surveillance DNSBL est vide. Un serveur combiné boîtes + hub ne pose
  simplement pas le profil.
* Les surfaces boîtes aux lettres sont désactivées (`[legacy] enabled = false`)
  et `[metrics] dnsbl_self_ips` est rempli avec les IP d'egress.
* L'enregistrement SPF du hub que les clients incluront
  (`spf.<domaine> TXT "v=spf1 ip4:… -all"`) est publié via Cloudflare si vous
  avez fourni un jeton, ou imprimé pour publication manuelle.
* **Aucun compte relais n'est créé.** Les clients relais entrent uniquement par
  des jetons frappés ; l'assistant imprime la commande
  `oximail account relay mint-token` comme étape suivante. Voir
  [Relais sortant & smarthost](./operator/outbound-relay) pour tout le
  parcours hub.

## Configuration non interactive

Pour des installations automatisées, écrivez un fichier TOML de setup et passez-le
avec `--config-file` :

```bash theme={null}
oximail setup --config-file setup.toml
```

Le fichier comporte une section `[server]` (`domain`, `hostname`, éventuellement
`deploy_mode = "primary"`, `"backup"` ou `"smarthost"`, `topology = "direct"`
ou `"proxy"`, `proxy_port`), ainsi que des sections facultatives `[dns]` (jeton Cloudflare,
`replace_existing_mx`), `[tls]` (`acme_email`), `[admin]` (`email` plus `password`
ou `password_file`, et un `default_timezone` optionnel), `[import]` (`source = "imap" | "jmap" | "mbox" | "skip"` avec
les champs de connexion correspondants), pour le mode secondaire, `[backup]`
(`primary_hostname`, `accepted_domains`, `mode`, `config_output_path`) et, pour
le déroulé smarthost, `[smarthost]` (`egress_ips = ["203.0.113.25", …]`,
validées comme littéraux IP, refus bruyant sinon).

Les mêmes étapes s'exécutent sans question. S'il n'y a pas de section `[admin]`,
l'assistant ne crée pas le compte administrateur et vous indique d'en créer un
avec `oximail account create`. Les mots de passe passés en mode non interactif
sont quand même contrôlés en force, et un mot de passe trop faible interrompt
l'exécution.

Utilisez `--dry-run` avec l'une de ces commandes pour prévisualiser la
configuration générée et les actions, sans rien écrire ni démarrer.

## Sous-commandes de setup individuelles

Chaque étape de l'assistant est aussi une sous-commande autonome sous
`oximail setup`, pratique pour rejouer un seul morceau :

```bash theme={null}
oximail setup dns --domain <d> --hostname <h> [--cloudflare-api-token <t>] [--replace-mx]
oximail setup dkim --domain <d> [--selector default]
oximail setup admin --email <e> [--password <p> | --password-file <f>] [--tenant-id default] [--config <chemin>]
oximail setup verify [--hostname <h>] [--config <chemin>]
```

Toutes acceptent `--dry-run`.

## Génération de clé DKIM

Il existe aussi une commande DKIM de premier niveau (distincte de
`oximail setup dkim`), celle qui est citée dans le démarrage rapide :

```bash theme={null}
oximail setup-dkim --domain <domaine> --selector <sélecteur> --config <chemin>
```

| Option        | Valeur par défaut           | Remarques                                                                                                                         |
| ------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--domain`    | (requis)                    | Domaine à signer, par exemple `oximail.ch`.                                                                                       |
| `--selector`  | (requis)                    | Sélecteur DKIM, par exemple `default`.                                                                                            |
| `--algorithm` | `rsa`                       | Seul `rsa` (RSA-2048) est accepté à l'exécution. `ed25519` est refusé car le signataire à l'exécution ne charge que des clés RSA. |
| `--config`    | `/etc/oximail/oximail.toml` | Sert à déterminer le répertoire de stockage de la clé.                                                                            |

Cette commande génère la paire de clés dans `/etc/oximail/dkim/` et affiche
l'enregistrement DNS DKIM à publier. Elle ne publie **pas** l'enregistrement sur
Cloudflare : seul l'assistant complet le fait, et seulement si un jeton est
fourni. Publiez vous-même la valeur affichée `v=DKIM1; k=rsa; p=...` sur
`<sélecteur>._domainkey.<domaine>`.

## Démarrer et vérifier à la main

Si vous avez sauté l'étape de démarrage de l'assistant, ou installé l'unité à la
main :

```bash theme={null}
systemctl daemon-reload
systemctl enable --now oximail
systemctl status oximail
journalctl -u oximail -f
```

Relancez les contrôles de l'assistant à tout moment :

```bash theme={null}
oximail setup verify --hostname mail.<domaine>
```

## Ce que l'assistant ne fait pas

* **Il n'installe pas le binaire.** Mettez d'abord `oximail` sur l'hôte ; voir
  [Installation](./installation).
* **Il ne publie pas le DNS sans Cloudflare.** Sans jeton Cloudflare, il affiche
  les enregistrements (ou les résultats du contrôle) à ajouter chez votre
  fournisseur.
* **Il ne publie pas le DKIM en dehors de l'assistant complet.** Les commandes
  autonomes `setup-dkim` et `setup dkim` génèrent et affichent l'enregistrement,
  mais ne le poussent pas vers le DNS.
* **Il ne configure pas le DKIM ed25519.** Seules des clés RSA-2048 sont générées
  et chargées à l'exécution.
* **Il ne gère pas votre pare-feu.** La vérification des ports se contente de
  signaler les ports bloqués ; leur ouverture dans le pare-feu du VPS ou le
  groupe de sécurité reste manuelle.
* **Il ne crée pas d'organisations ni de comptes supplémentaires.** Il provisionne
  exactement un tenant `default` et un compte administrateur. Ajoutez-en d'autres
  avec `oximail tenant create` et `oximail account create`.

## Étapes suivantes

* [Configuration](./operator/configuration) : ajustez les valeurs écrites par l'assistant.
* [TLS et ACME](./operator/tls-acme) : gestion des certificats, en direct et derrière un proxy.
* [Authentification et sécurité du courrier](./operator/email-auth-security) : détails SPF, DKIM, DMARC.
* [Migration](./operator/migration) : importer du courrier depuis un serveur existant.
* [Référence CLI](./operator/cli) : la liste complète des commandes.