Reshape the documentation

content/introduction/deploy/_index.en.md

@@ -0,0 +1,13 @@
+---
+date: 2021-01-12T21:38:49+02:00
+title: Installation and deployment
+archetype: chapter
+weight: 40
+---
+
+Depending on your concerns, happyDomain can be deployed in different kind of environment.
+Thanks to some modularity, there is certainly a path to your needs.
+
+---
+
+{{% children %}}

content/introduction/deploy/_index.fr.md

@@ -0,0 +1,13 @@
+---
+date: 2020-12-09T19:23:38+01:00
+title: Installation et deploiement
+archetype: chapter
+weight: 40
+---
+
+Selon vos besoins, happyDomain peut être déployé de différentes manières selon votre environnement.
+Grâce à plusieurs éléments modulables, il y a certainement une voie correspondant à vos attentes.
+
+---
+
+{{% children %}}

content/introduction/deploy/bind.en.md

@@ -0,0 +1,102 @@
+---
+data: 2024-06-26T20:44:25+02:00
+title: Connect to a remote BIND server
+weight: 30
+---
+
+[BIND](https://www.isc.org/bind/) is an authoritative and recursive DNS server developed by the [Internet Systems Consortium](https://isc.org).
+
+It is possible to use it with happyDomain through [Dynamic DNS (RFC 2136)](https://www.rfc-editor.org/rfc/rfc2136).
+
+This documentation will guide you through configuring BIND to enable Dynamic DNS and connect your domains to happyDomain.
+
+
+## Configure BIND to enable Dynamic DNS
+
+First, you need to edit the main BIND configuration file (usually `/etc/named.conf` or `/etc/bind/named.conf` depending on your distribution) to add a secret that will be shared between happyDomain and BIND to authenticate the changes. Then you must indicate which domains will be managed by happyDomain.
+
+### Adding a Shared Secret
+
+Under the main `key` section of your configuration, add the following key:
+
+```conf
+key "happydomain" {
+    algorithm hmac-sha512;
+    secret "<SOME_SECRET>";
+};
+```
+
+Replace `<SOME_SECRET>` with a string obtained using `openssl rand -base64 48`.
+
+### Creating an Authorization Rule for happyDomain
+
+In addition to the key, you must specify how the key can be used by defining an ACL and allowing updates from it.
+
+Add the following ACL to your configuration:
+
+```conf
+acl "happydomain_acl" {
+    key happydomain;
+};
+```
+
+### Allowing Updates for Each Zone
+
+Now that you have created a rule allowing the `happydomain` key to make changes, you need to indicate to which zones this rule applies.
+
+For each zone, you must add an `update-policy` statement referencing the `happydomain_acl` ACL:
+
+For example, for an existing `happydomain.org` zone, add the `update-policy` statement as follows:
+
+```conf
+zone "happydomain.org" {
+    type master;
+    file "/var/named/happydomain.org.db";
+    update-policy {
+        grant happydomain_acl name happydomain.org. ANY;
+    };
+};
+```
+
+The `update-policy` statement is a list, so you may already have other policies in this list. In this case, just add the `grant` statement for `happydomain_acl`.
+
+### Allowing Updates for All Zones
+
+If you manage many zones, it may be more convenient to set the default authorization for all zones. In this case, you can use a `global` `update-policy` in the `options` section:
+
+```conf
+options {
+    update-policy {
+        grant happydomain_acl zonesub ANY;
+    };
+};
+```
+
+This will apply the `update-policy` to all zones, allowing the `happydomain_acl` to update any record.
+
+### Apply the Configuration
+
+After modifying the configuration file, reload the BIND service to apply the changes:
+
+```sh
+rndc reload
+```
+
+## Link happyDomain and BIND
+
+Once BIND is well configured, you can link it to happyDomain using [the *Dynamic DNS* connector]({{% ref "/pages/provider-new-choice.md" %}}) :
+
+![The Dynamic DNS connector on the host selection page](/img/choose-dynamic-dns.png)
+
+Follow these steps:
+
+1. Navigate to the Dynamic DNS connector on the host selection page in happyDomain.
+2. Fill in the form with the address where your BIND server is accessible.
+3. Fill in the Key fields with the information from the `key` section in the BIND configuration:
+    - **Key Name**: corresponds to the key name in BIND's configuration (e.g., `happydomain`).
+    - **Key Algorithm**: corresponds to the algorithm (e.g., `hmac-sha512`).
+    - **Secret Key**: corresponds to the secret.
+
+Once the provider is added, it does not allow you to list existing domains, but you can still manually add all your domains.
+
+By following these steps, you will have configured BIND to work with happyDomain using Dynamic DNS, ensuring secure and authenticated DNS updates.

content/introduction/deploy/bind.fr.md

@@ -0,0 +1,99 @@
+---
+data: 2024-06-26T20:44:25+02:00
+title: Connexion à un serveur BIND distant
+weight: 30
+---
+
+[BIND](https://www.isc.org/bind/) est un serveur DNS récursif et faisant autorité développé par l'[Internet Systems Consortium](https://isc.org).
+
+Il est possible de l'utiliser avec happyDomain en passant par le [Dynamic DNS (RFC 2136)](https://www.rfc-editor.org/rfc/rfc2136).
+
+Cette documentation vous guidera dans la configuration de BIND pour activer le DNS dynamique, puis pour relier ensemble happyDoain et votre serveur BIND.
+
+
+## Configurer BIND pour activer le DNS dynamique
+
+Tout d'abord, vous devez modifier le fichier de configuration principal de BIND (généralement `/etc/named.conf` ou `/etc/bind/named.conf` selon votre distribution) pour ajouter un secret qui sera partagé entre happyDomain et BIND pour authentifier les modifications. Ensuite, vous devez indiquer quels domaines seront gérés par happyDomain.
+
+### Ajouter un secret partagé
+
+Sous la section principale `key` de votre configuration, ajoutez la clé suivante :
+
+```conf
+key "happydomain" {
+    algorithm hmac-sha512;
+    secret "<SOME_SECRET>";
+};
+```
+
+Remplacez `<SOME_SECRET>` par une chaîne obtenue en utilisant `openssl rand -base64 48`.
+
+### Créer une règle d'autorisation pour happyDomain
+
+En plus de la clé, vous devez spécifier comment la clé peut être utilisée en définissant une ACL et en autorisant les mises à jour à partir de celle-ci.
+
+Ajoutez l'ACL suivante à votre configuration :
+
+```conf
+acl "happydomain_acl" {
+    key happydomain;
+};
+```
+
+### Autoriser les mises à jour pour chaque zone
+
+Maintenant que vous avez créé une règle permettant à la clé `happydomain` d'apporter des modifications, vous devez indiquer à quelles zones cette règle s'applique.
+
+Pour chaque zone, vous devez ajouter une déclaration `update-policy` référencant l'ACL `happydomain_acl` :
+
+Par exemple, pour une zone existante `happydomain.org`, ajoutez la déclaration `update-policy` comme suit :
+
+```conf
+zone "happydomain.org" {
+    type master;
+    file "/var/named/happydomain.org.db";
+    update-policy {
+        grant happydomain_acl name happydomain.org. ANY;
+    };
+};
+```
+
+La déclaration `update-policy` est une liste, donc vous pouvez déjà avoir d'autres politiques dans cette liste. Dans ce cas, ajoutez simplement la déclaration `grant` pour `happydomain_acl`.
+
+### Autoriser les mises à jour pour routes les zones
+
+Si vous gérez de nombreuses zones, il peut être plus pratique de définir l'autorisation par défaut pour toutes les zones. Dans ce cas, vous pouvez utiliser une `update-policy` globale dans la section `options` :
+
+```conf
+options {
+    update-policy {
+        grant happydomain_acl zonesub ANY;
+    };
+};
+```
+
+Cela appliquera la `update-policy` à toutes les zones, permettant à l'ACL `happydomain_acl` de mettre à jour n'importe quel enregistrement.
+
+### Appliquer la configuration
+
+Après avoir modifié le fichier de configuration, rechargez le service BIND pour appliquer les modifications :
+
+```sh
+rndc reload
+```
+
+## Lier happyDomain et BIND
+
+Une fois BIND bien configuré, vous pouvez le lier à happyDomain en utilisant [le connecteur *Dynamic DNS*]({{% ref "/pages/provider-new-choice.md" %}}) :.
+
+![Le connecteur Dynamic DNS sur la page de choix de l'hébergeur](/img/choose-dynamic-dns.png)
+
+Remplissez ensuite le formulaire avec l'adresse à laquelle votre serveur BIND est accessible, puis ensuite les différents champs *Key* avec les informations indiqués dans votre configuration :
+
+- **Key Name** : correspond au champ `id` ;
+- **Key Algorithm** : correspond au champ `algorithm` ;
+- **Secret Key** : correspond au champ `secret`.
+
+Une fois le fournisseur ajouté, il ne permet pas de lister les domaines existants, mais vous pouvez toujours ajouter manuellement tous vos domaines.
+
+En suivant ces étapes, vous aurez configuré BIND pour fonctionner avec happyDomain en utilisant le DNS dynamique, assurant des mises à jour DNS sécurisées et authentifiées.

content/introduction/deploy/config.en.md

@@ -0,0 +1,189 @@
+---
+data: 2023-02-11T11:58:55+01:00
+title: Configuration
+weight: 20
+---
+
+happyDomain respects the methodology [*12 factor*](https://12factor.net/) and allows to act on the application configuration in several ways.
+
+## How do I configure happyDomain?
+
+It is possible to configure happyDomain in three different ways: configuration file, environment, command line. All options are available for each of these mechanisms.
+
+The precedence, when an option is defined by several mechanisms simultaneously, is that an option present in a configuration file will be overwritten by the environment, which will be overwritten by an option passed on the command line
+
+
+### Configuration by file
+
+When the application is launched, the first configuration file from the following list will be used:
+
+- `./happydomain.conf`
+- `$XDG_CONFIG_HOME/happydomain/happydomain.conf`
+- `/etc/happydomain.conf`
+
+**Only the first existing file is taken into account.** It is not possible to have part of its options in `/etc/happydomain.conf` and part in `./happydomain.conf`, only the latter configuration file will be taken into account.
+
+It is possible to specify a custom path by adding it as an additional parameter to the command line. Thus, to use the configuration file located at `/etc/happydomain/config`, we would use :
+
+```
+./happydomain /etc/happydomain/config
+```
+
+#### Configuration file format
+
+Comments line has to begin with `#`, it is not possible to have comments at the end of a line, by appending `#` followed by a comment.
+
+Place on each line the name of the config option and the expected value, separated by `=`. For example:
+
+```
+storage-engine=leveldb
+leveldb-path=/var/lib/happydomain/db/
+```
+
+### Configuration by the environment
+
+When happyDomain is started, all variables beginning with `HAPPYDOMAIN_` are scanned for valid configuration options.
+
+You can do the same thing as in the previous example, with the following environment variables:
+
+```
+HAPPYDOMAIN_STORAGE_ENGINE=leveldb
+HAPPYDOMAIN_LEVELDB_PATH=/var/lib/happydomain/db/
+```
+
+You just have to replace dash by underscore.
+
+
+### Command line configuration
+
+Finally, the command line can be used to pass options, according to the usual UNIX format.
+
+To continue the previous example, we can perform the same configuration with the following command line:
+
+```
+./happydomain -storage-engine leveldb -leveldb-path /var/lib/happydomain/db/
+```
+
+or by using the `=` sign to clearly assign the value.
+
+```
+./happydomain -storage-engine=leveldb -leveldb-path=/var/lib/happydomain/db/
+```
+
+
+## Configuration items
+
+The complete list of configurable items can be listed by calling `happyDomain` with the `-h` or `--help` option.
+
+Here is a list of the main options:
+
+### General parameters
+
+`bind`
+: Bind port/socket to use to expose happyDomain.
+
+`admin-bind`
+: Bind port/socket to use to expose the administration API.
+
+`default-ns`
+: Address and port of the name resolver server to be used by default when name resolution is required.
+
+`dev`
+: URL to which all requests related to the graphical interface will be returned.
+
+`externalurl`
+: URL of the service, as it should appear in emails and content to the public.
+
+`disable-providers-edit`
+: Disallow all actions on provider (add/edit/delete), eg. for demo mode.
+
+
+#### Page layout
+
+`custom-head-html`
+: String to be placed before the end of the HTML header.
+
+`custom-body-html`
+: String to be placed before the end of the HTML body.
+
+`hide-feedback-button`
+: Hide the icon on page that permit to give feedback.
+
+`msg-header-text`
+: Custom message banner to add at the top of the app.
+
+`msg-header-color`
+: Background color class of the banner added at the top of the app (default "danger", can be primary, secondary, info, success, warning, danger, light, dark, or any bootstrap color class).
+
+
+### Data storage
+
+`storage-engine`
+: Allows you to choose the data storage mechanism among all supported mechanisms.
+
+### LevelDB (`storage-engine=leveldb`)
+
+`leveldb-path`
+: Path to the folder containing the LevelDB database to use.
+
+### E-Mail parameters
+
+We use [`go-mail`](https://github.com/go-mail/mail) as a library to send mails.
+
+`mail-from`
+: Defines the name and address of the sender of emails sent by the service.
+
+Note that without the `mail-smtp-*` options, happyDomain will use the `sendmail` binary to send mail. This can be coupled with the `msmtp` or `ssmtp` packages, for example, to set the parameters for the whole system.
+
+`mail-smtp-host`
+: IP or host name of the SMTP server to use.
+
+`mail-smtp-port`
+: Port to use on the remote server.
+
+`mail-smtp-username`
+: When authentication is required on the remote server, username to use.
+
+`mail-smtp-password`
+: When authentication is required on the remote server, password to use.
+
+
+### Authentication
+
+`no-auth`
+: Disables the notion of users and access control. A default account is used.
+
+`disable-embedded-login`
+: Disables the internal user/password login in favor of external-auth or OIDC.
+
+`disable-registration`
+: Forbids new account creation through public form/API (still allow registration from external services).
+
+`external-auth`
+: URL base of the authentication and registration service to be used instead of the embedded login system.
+
+`jwt-secret-key`
+: Secret key used to verify JWT tokens.
+
+See also [OpenID Connect settings]({{% relref "oidc" %}}).
+
+
+### Specific to registrars
+
+Some registrars require third-party applications to identify themselves in addition to the user.
+
+#### Bind
+
+`with-bind-provider`
+: Enable the BIND provider (not suitable for cloud/shared instance as it'll access the local file system).
+
+
+#### OVH
+
+Please refer to [this documentation]({{% relref "ovh" %}}) to generate the identifiers.
+
+`ovh-application-key`
+: Application key for OVH API.
+
+`ovh-application-secret`
+: Secret key for OVH API.

content/introduction/deploy/config.fr.md

@@ -0,0 +1,188 @@
+---
+data: 2023-02-11T11:58:55+01:00
+title: Configuration
+weight: 20
+---
+
+happyDomain respecte la méthodologie [*12 factor*](https://12factor.net/) et permet notamment d'agir sur la configuration de l'application de plusieurs manières.
+
+## Par quels moyens configurer happyDomain ?
+
+Il est possible de configurer happyDomain de trois manières différentes : fichier de configuration, environnement, ligne de commande. Toutes les options sont disponibles pour chacun de ces mécanismes.
+
+La précédence, lorsqu'une option est définie par plusieurs mécanismes simultanément, est qu'une option présente dans un fichier de configuration sera écrasé par l'environnement, qui sera écrasée par une option passée sur la ligne de commande.
+
+### Configuration par fichier
+
+Au lancement de l'application, le premier fichier de configuration parmi la liste suivante sera utilisé :
+
+- `./happydomain.conf`
+- `$XDG_CONFIG_HOME/happydomain/happydomain.conf`
+- `/etc/happydomain.conf`
+
+**Seulement le premier fichier existant est pris en compte.** Il n'est pas possible d'avoir une partie de ses options dans `/etc/happydomain.conf` et une autre dans `./happydomain.conf`, seul ce dernier fichier de configuration sera pris en compte.
+
+Il est possible de préciser un chemin personnalisé en l'ajoutant comme paramètre supplémentaire à la ligne de commande. Ainsi, pour utiliser le fichier de configuration situé à `/etc/happydomain/config`, on utilisera :
+
+```
+./happydomain /etc/happydomain/config
+```
+
+#### Format du fichier de configuration
+
+Une ligne de commentaires commence par `#`, il n'est pas possible d'avoir des commentaires à la fin d'une ligne, en ajoutant `#` suivi d'un commentaire.
+
+Placez sur chaque ligne le nom de l'option de configuration et la valeur attendue, séparés par `=`. Par exemple :
+
+```
+storage-engine=leveldb
+leveldb-path=/var/lib/happydomain/db/
+```
+
+### Configuration par l'environnement
+
+Au lancement d'happyDomain, toutes les variables commençant par `HAPPYDOMAIN_` sont analysées à la recherche d'options de configuration valides.
+
+Vous pouvez réaliser la même chose que dans l'exemple précédent, avec les variables d'environnement suivantes :
+
+```
+HAPPYDOMAIN_STORAGE_ENGINE=leveldb
+HAPPYDOMAIN_LEVELDB_PATH=/var/lib/happydomain/db/
+```
+
+Notez que les `-` sont remplacés par des `_` dans les variables d'environnement.
+
+
+### Configuration par la ligne de commande
+
+Enfin, la ligne de commande peut être utilisée pour passer des options, selon le format UNIX usuel.
+
+Pour continuer l'exemple précédent, nous pouvons réaliser la même configuration avec la ligne de commande suivante :
+
+```
+./happydomain -storage-engine leveldb -leveldb-path /var/lib/happydomain/db/
+```
+
+ou encore en utilisant le signe `=` pour assigner clairement la valeur.
+
+```
+./happydomain -storage-engine=leveldb -leveldb-path=/var/lib/happydomain/db/
+```
+
+
+## Éléments de configuration
+
+La liste exhaustive des éléments configurables peut être listé en appelant `happyDomain` avec l'option `-h` ou `--help`.
+
+Voici la liste des principales options :
+
+### Paramètres généraux
+
+`bind`
+: Interface (ip, port) à utiliser pour exposer le service happyDomain.
+
+`admin-bind`
+: Interface (ip, port ou socket) à utiliser pour exposer l'API d'administration.
+
+`default-ns`
+: Adresse et port du serveur résolveur de noms à utiliser par défaut lorsqu'une résolution de nom est nécessaire.
+
+`dev`
+: URL vers laquelle toutes les requêtes liées à l'interface graphique seront renvoyées.
+
+`externalurl`
+: URL du service, tel qu'il doit apparaître dans les mails et contenus à destination du public.
+
+`disable-providers-edit`
+: Interdit toute action sur les fournisseurs de service DNS (ajour/édition/suppression), par exemple pour avoir un mode de démonstration.
+
+
+#### Mise en page
+
+`custom-head-html`
+: Chaîne de caractères à placer avant la fin de l'en-tête HTML.
+
+`custom-body-html`
+: Chaîne de caractères à placer avant la fin du corps HTML.
+
+`hide-feedback-button`
+: Cache l'icône permettant de donner son retour d'expérience.
+
+`msg-header-text`
+: Ajoute un message personnalisé dans une bannière en haut de toutes les pages.
+
+`msg-header-color`
+: Classe de couleur de fond pour la bannière ajoutée en haut de l'application web (par défaut "danger", pourrait être primary, secondary, info, success, warning, danger, light, dark, ou toute autre classe de couleur bootstrap).
+
+
+### Stockage des données
+
+`storage-engine`
+: Permet de choisir le mécanisme de stockage des données parmi tous les mécanismes supportés.
+
+### LevelDB (`storage-engine=leveldb`)
+
+`leveldb-path`
+: Chemin vers le dossier contenant la base LevelDB à utiliser.
+
+### Paramètres e-mail
+
+Nous employons [`go-mail`](https://github.com/go-mail/mail) comme bibliothèque pour envoyer les mails.
+
+`mail-from`
+: Définit le nom et l'adresse de l'expéditeur des mails envoyés par le service.
+
+Notez que sans les options `mail-smtp-*`, happyDomain utilisera le binaire `sendmail` pour envoyer les mails. Cela peut être couplé aux paquets `msmtp` ou `ssmtp` par exemple, pour définir les paramètres pour tout le système.
+
+`mail-smtp-host`
+: IP ou nom d'hôte du serveur SMTP à utiliser.
+
+`mail-smtp-port`
+: Port à utiliser sur le serveur distant.
+
+`mail-smtp-username`
+: Lorsque de l'authentification est nécessaire sur le serveur distant, nom d'utilisateur à utiliser.
+
+`mail-smtp-password`
+: Lorsque de l'authentification est nécessaire sur le serveur distant, mot de passe à utiliser.
+
+
+### Authentification
+
+`no-auth`
+: Désactive la notion d'utilisateurs et de contrôle d'accès. Un compte par défaut est utilisé.
+
+`disable-embedded-login`
+: Désactive le mécanisme de connexion interne en faveur de l'external-auth ou d'OIDC.
+
+`disable-registration`
+: Interdit la création de nouveau compte à travers le formulaire ou l'API (cela ne désactive pas la création de compte lorsque l'on se connecte pour la première fois à partir d'un service d'authentification externe).
+
+`external-auth`
+: Base de l'URL du service d'authentification et d'enregistrement à utiliser à la place du système de connexion embarqué.
+
+`jwt-secret-key`
+: Clef secrète utilisée pour vérifier les tokens JWT.
+
+Voir aussi [paramètres OpenID Connect]({{% relref "oidc" %}}).
+
+
+### Spécifique aux bureaux d'enregistrement
+
+Certain bureau d'enregistrement nécessitent que les applications tierces s'identifient en plus d'identifier l'utilisateur.
+
+#### Bind
+
+`with-bind-provider`
+: Active BIND en tant que fournisseur DNS (attention, ce paramètre n'est pas adapté à un environnement partagé/cloud car il accède au système de fichiers local).
+
+
+#### OVH
+
+Veuillez vous référer à [cette documentation]({{% relref "ovh" %}}) afin de générer les identifiants.
+
+`ovh-application-key`
+: Application key pour l'API d'OVH
+
+`ovh-application-secret`
+: Clef secrète pour l'API d'OVH

content/introduction/deploy/docker.en.md

@@ -0,0 +1,75 @@
+---
+data: 2023-01-19T19:31:08+02:00
+title: Using Docker
+weight: 15
+---
+
+happyDomain is sponsored by Docker.
+You'll find the official container image on [the Docker Hub](https://hub.docker.com/r/happydomain/happydomain/).
+
+This image will run happyDomain as a single process, with a LevelDB database (similarly to sqlite, LevelDB is stored on disk, no need to configure anything).
+
+
+## Supported tags and architectures
+
+All tags are build for `amd64`, `arm64` and `arm/v7` and are based on alpine.
+
+Currently, available tags are:
+
+- `latest`: this is a the most up to date version, corresponding to the master branch.
+
+## Using this image
+
+### For testing purpose
+
+You can test happyDomain or use it for your own usage, with the option `HAPPYDOMAIN_NO_AUTH=1`: this will automatically creates a default account, and disable all features related to the user management (signup, login, ...).
+
+```
+docker run -e HAPPYDOMAIN_NO_AUTH=1 -p 8081:8081 happydomain/happydomain
+```
+
+Data are stored in `/data` directory. If you want to keep your settings from one run to another, you'll need to attach this directory to a Docker managed volume or to a directory on your host:
+
+```
+docker volume create happydomain_data
+docker run -e HAPPYDOMAIN_NO_AUTH=1 -v happydomain_data:/data -p 8081:8081 happydomain/happydomain
+```
+
+### In production
+
+happyDomain needs to send e-mail, in order to verify addresses and doing password recovery, so you need basically to configure a SMTP relay.
+Use the options `HAPPYDOMAIN_MAIL_SMTP_HOST`, `HAPPYDOMAIN_MAIL_SMTP_PORT` (default 25), `HAPPYDOMAIN_MAIL_SMTP_USERNAME` and `HAPPYDOMAIN_MAIL_SMTP_PASSWORD` for this purpose:
+
+```
+docker run -e HAPPYDOMAIN_MAIL_SMTP_HOST=smtp.yourcompany.com -e HAPPYDOMAIN_MAIL_SMTP_USERNAME=happydomain -e HAPPYDOMAIN_MAIL_SMTP_PASSWORD=secret -v /var/lib/happydomain:/data -p 8081:8081 happydomain/happydomain
+```
+
+If you prefer using a configuration file, you can place it either in `/data/happydomain.conf` to use the volume, or bind your file to `/etc/happydomain.conf`:
+
+```
+docker run -v happydomain.conf:/etc/happydomain.conf -p 8081:8081 happydomain/happydomain
+```
+
+#### Extend the base image
+
+By default, happyDomain uses `sendmail`, if you prefer, you can create you own image with the package `ssmtp`:
+
+```
+FROM happydomain/happydomain
+RUN apk --no-cache add ssmtp
+COPY my_ssmtp.conf /etc/ssmtp/ssmtp.conf
+```
+
+
+## Admin Interface
+
+happyDomain exposes some administration command through a unix socket. The docker container contains a script to access this admin part: `hadmin`.
+
+You can use it this way:
+
+```
+docker exec my_container hadmin /api/users
+docker exec my_container hadmin /api/users/0123456789/send_validation_email -X POST
+```
+
+This is in fact a wrapper above `curl`, but you have to start by the URL, and place options after it.

content/introduction/deploy/docker.fr.md

@@ -0,0 +1,81 @@
+---
+data: 2023-01-19T19:31:08+02:00
+title: Avec Docker
+weight: 15
+---
+
+happyDomain est sponsorisé Docker.
+Vous trouverez notre image officielle sur [le Docker Hub](https://hub.docker.com/r/happydomain/happydomain/).
+
+Cette image exécutera happyDomain en tant que processus unique, avec une base de données LevelDB (similaire à sqlite, LevelDB est une base de données stockée sur le disque, il n'est pas nécessaire de configurer quoi que ce soit d'autre).
+
+
+## Versions, étiquettes and architectures supportés
+
+Toutes les étiquettes (*tags*) sont construites pour les architectures de processeur les plus courantes (`amd64`, `arm64` et `arm/v7`).
+Nous ne construisons des images uniquement basées sur la distribution Alpine Linux, ce qui assure des images de taille minimale.
+
+Actuellement, les étiquettes disponibles sont :
+
+- `latest`: il s'agit de la version la plus récente, correspondant à la branche `master` de notre dépôt de sources.
+
+
+## Utilisation de l'image
+
+### À des fins de test
+
+Vous pouvez tester happyDomain ou l'utiliser pour votre usage personnel, avec l'option `HAPPYDOMAIN_NO_AUTH=1` : cela créera automatiquement un compte par défaut, et désactivera toutes les fonctionnalités liées à la gestion des utilisateurs (inscription, connexion, ...).
+
+```
+docker run -e HAPPYDOMAIN_NO_AUTH=1 -p 8081:8081 happydomain/happydomain
+```
+
+Les données sont stockées dans le répertoire `/data`.
+Si vous souhaitez conserver vos paramètres d'une exécution à l'autre, vous devrez attacher ce répertoire à un volume géré par Docker ou à un répertoire sur votre hôte :
+
+```
+docker volume create happydomain_data
+docker run -e HAPPYDOMAIN_NO_AUTH=1 -v happydomain_data:/data -p 8081:8081 happydomain/happydomain
+```
+
+
+### En production
+
+happyDomain a besoin d'envoyer du courrier électronique, afin de vérifier les adresses et d'effectuer la récupération des mots de passe, vous devez donc configurer un relais SMTP.
+Utilisez les options `HAPPYDOMAIN_MAIL_SMTP_HOST`, `HAPPYDOMAIN_MAIL_SMTP_PORT` (par défaut 25), `HAPPYDOMAIN_MAIL_SMTP_USERNAME` et `HAPPYDOMAIN_MAIL_SMTP_PASSWORD` à cette fin :
+
+```
+docker run -e HAPPYDOMAIN_MAIL_SMTP_HOST=smtp.yourcompany.com -e HAPPYDOMAIN_MAIL_SMTP_USERNAME=happydomain -e HAPPYDOMAIN_MAIL_SMTP_PASSWORD=secret -v /var/lib/happydomain:/data -p 8081:8081 happydomain/happydomain
+```
+
+Si vous préférez utiliser un fichier de configuration, vous pouvez le placer soit dans `/data/happydomain.conf` pour utiliser le volume, soit lier votre fichier à `/etc/happydomain.conf` :
+
+```
+docker run -v happydomain.conf:/etc/happydomain.conf -p 8081:8081 happydomain/happydomain
+```
+
+
+#### Étendre l'image de base
+
+Par défaut, happyDomain utilise `sendmail`, si vous préférez, vous pouvez créer votre propre image avec le paquet `ssmtp` :
+
+```
+FROM happydomain/happydomain
+RUN apk --no-cache add ssmtp
+COPY my_ssmtp.conf /etc/ssmtp/ssmtp.conf
+```
+
+
+## Interface d'administration
+
+happyDomain expose certaines commandes d'administration à travers un socket unix.
+Le conteneur docker contient un script pour accéder à cette partie d'administration : `hadmin`.
+
+Vous pouvez l'utiliser de cette manière :
+
+```
+docker exec my_container hadmin /api/users
+docker exec my_container hadmin /api/users/0123456789/send_validation_email -X POST
+```
+
+Il s'agit en fait d'une surcouche au-dessus de `curl`, mais vous devez commencer par l'URL, et placer les options après.

content/introduction/deploy/knot.en.md

@@ -0,0 +1,108 @@
+---
+data: 2023-02-09T09:12:25+01:00
+title: Connect to a local knot
+weight: 31
+---
+
+[Knot](https://knot-dns.cz) is an authoritative DNS server developed by the [cz.nic](https://nic.cz) association.
+
+It is possible to use it with happyDomain through [Dynamic DNS (RFC 2136)](https://www.rfc-editor.org/rfc/rfc2136).
+
+
+## Configure Knot to enable Dynamic DNS
+
+First, you have to edit the main knot configuration file (usually `/etc/knot/knot.conf`) to add a secret that will be shared between happyDomain and knot to authenticate the changes. Then you have to indicate which domains will be managed by happyDomain.
+
+### Adding a shared secret {#shared-secret}
+
+Under the main [`key`](https://knot.readthedocs.io/en/latest/reference.html#key-section) section of your configuration, add the following key:
+
+```yaml
+key:
+  [...]
+  - id: happydomain
+    algorithm: hmac-sha512
+    secret: "<SOME_SECRET>"
+```
+
+Obviously replace `<SOME_SECRET>` with a string as obtained with `openssl rand -base64 48`.
+
+
+### Creating an authorization rule for happyDomain
+
+In addition to the key, you must specify in the configuration how the key can be used.
+
+To do this, under the main [`acl`](https://knot.readthedocs.io/en/latest/reference.html#acl-section) section, we add:
+
+```yaml
+acl:
+  [...]
+  - id: acl_happydomain
+    key: happydomain
+    action: transfer
+    action: update
+```
+
+This associates the `key` defined just before with the actions `transfer` and `update`, respectively to allow retrieving the zone and to update records.
+
+
+### Associate the authorization to each zone
+
+Now that you have created a rule allowing the `happydomain` key to make changes, you need to indicate to which zones this rule applies.
+
+For each [zone](https://knot.readthedocs.io/en/latest/reference.html#zone-section), you must add an [`acl`](https://knot.readthedocs.io/en/latest/reference.html#acl) element referencing the `acl_happydomain` rule:
+
+For example, for an existing `happydomain.org` zone, we will add the `acl` line as follows:
+
+```yaml
+zone:
+  [...]
+  - domain: happydomain.org
+    acl:
+      - acl_happydomain
+    [...]
+```
+
+The `acl` element is a list, so you may already have other acl elements in this list. In this case you just need to add the `acl_happydomain` element to the already existing list.
+
+You have to add this `acl` element for each zone, unless you use the following trick.
+
+
+### Associate the authorization to all zones
+
+If you manage many zones, it may be more convenient to set the default authorization for all zones. In this case, instead of the previous section, we will modify the `default` template:
+
+```yaml
+template:
+  - id: default
+    acl:
+      - acl_happydomain
+  [...]
+```
+
+The `default` template is applied to all zones by default. By doing so, all zones will inherit the `acl_happydomain` rule.
+
+
+### Apply the configuration
+
+Now that the configuration file has been modified, tell `knotd` to reload its configuration:
+
+```sh
+knotc reload
+```
+
+
+## Link happyDomain and knot
+
+
+Once `knot` well configured, you can link it to happyDomain using [the *Dynamic DNS* connector]({{% ref "/pages/provider-new-choice.md" %}}) :
+
+![The Dynamic DNS connector on the host selection page](/img/choose-dynamic-dns.png)
+
+Then fill in the form with the address where your `knot` server is accessible, then fill in the different *Key* fields with [the information from the `knot`'s `key` section](#shared-secret):
+
+- **Key Name** : corresponds to `id` in knot's configuration ;
+- **Key Algorithm** : corresponds to `algorithm` ;
+- **Secret Key** : corresponds to `secret`.
+
+Once the provider is added, it does not allow you to list existing domains, but you can still manually add all your domains.

content/introduction/deploy/knot.fr.md

@@ -0,0 +1,107 @@
+---
+data: 2023-02-09T08:03:25+01:00
+title: Connexion à un knot local
+weight: 31
+---
+
+[Knot](https://knot-dns.cz) est un serveur DNS faisant autorité développé par l'association [cz.nic](https://nic.cz).
+
+Il est possible de l'utiliser avec happyDomain en passant par le [Dynamic DNS (RFC 2136)](https://www.rfc-editor.org/rfc/rfc2136).
+
+
+## Configurer Knot pour permettre le Dynamic DNS
+
+Tout d'abord, il faut éditer le fichier de configuration principal de knot (généralement `/etc/knot/knot.conf`) afin d'ajouter un secret qui sera partagé entre happyDomain et knot pour authentifier les modifications. Puis il faudra indiquer quels domaines vont être gérés par happyDomain.
+
+### Ajout d'un secret partagé {#shared-secret}
+
+Sous la section principale [`key`](https://knot.readthedocs.io/en/latest/reference.html#key-section) de votre configuration, ajoutez la clef suivante :
+
+```yaml
+key:
+  [...]
+  - id: happydomain
+    algorithm: hmac-sha512
+    secret: "<SOME_SECRET>"
+```
+
+Remplacez évidemment `<SOME_SECRET>` par une chaîne de caractères telle qu'obtenue avec `openssl rand -base64 48`.
+
+
+### Création d'une autorisation pour happyDomain
+
+En plus de la clef, vous devez préciser dans la configuration comment la clef peut être utilisée.
+
+Pour cela, sous la section principale [`acl`](https://knot.readthedocs.io/en/latest/reference.html#acl-section), on ajoute :
+
+```yaml
+acl:
+  [...]
+  - id: acl_happydomain
+    key: happydomain
+    action: transfer
+    action: update
+```
+
+Cela associe la `key` définie juste avant aux actions `transfer` et `update`, respectivement pour permettre de récupérer la zone et pour mettre à jour des enregistrements.
+
+
+### Associer l'autorisation à chaque zone
+
+Maintenant que vous avez créé une règle autorisant la clef `happydomain` à apporter des modifications, il faut indiquer à quelles zones cette règle s'applique.
+
+Pour chaque [zone](https://knot.readthedocs.io/en/latest/reference.html#zone-section), il faut ajouter un élément [`acl`](https://knot.readthedocs.io/en/latest/reference.html#acl) référençant la règle `acl_happydomain` :
+
+Par exemple, pour une zone `happydomain.org` déjà existante, on ajoutera la ligne `acl` comme suit :
+
+```yaml
+zone:
+  [...]
+  - domain: happydomain.org
+    acl:
+      - acl_happydomain
+    [...]
+```
+
+L'élément `acl` est une liste, vous pouvez donc avoir déjà d'autres éléments `acl` dans cette liste. Il convient alors d'ajouter simplement l'élément `acl_happydomain` à la liste déjà existante.
+
+Il faut ajouter cet élément `acl` pour chaque zone, sauf à utiliser l'astuce suivante.
+
+
+### Associer l'autorisation à toutes les zones
+
+Si vous gérez de nombreuses zones, il peut être plus pratique de définir l'autorisation par défaut pour toutes les zones. Dans ce cas, à la place de la section précédente, on modifiera le modèle `default` :
+
+```yaml
+template:
+  - id: default
+    acl:
+      - acl_happydomain
+  [...]
+```
+
+Le modèle `default` est appliqué par défaut à toutes les zones. En faisant ainsi, toutes les zones hériteront de la règle `acl_happydomain`.
+
+
+### Appliquer la configuration
+
+Maintenant que le fichier de configuration a été modifié, indiquez à `knotd` qu'il doit recharger sa configuration :
+
+```sh
+knotc reload
+```
+
+
+## Liaison entre happyDomain et knot
+
+Une fois `knot` bien configuré, vous pouvez le relier à happyDomain en utilisant [le connecteur *Dynamic DNS*]({{% ref "/pages/provider-new-choice.md" %}}) :
+
+![Le connecteur Dynamic DNS sur la page de choix de l'hébergeur](/img/choose-dynamic-dns.png)
+
+Remplissez ensuite le formulaire avec l'adresse à laquelle votre serveur `knot` est accessible, puis ensuite les différents champs *Key* avec [les informations de la section `key` de `knot`](#shared-secret) :
+
+- **Key Name** : correspond au champ `id` ;
+- **Key Algorithm** : correspond au champ `algorithm` ;
+- **Secret Key** : correspond au champ `secret`.
+
+Une fois le fournisseur ajouté, il ne permet pas de lister les domaines existants, mais vous pouvez tout de même ajouter manuellement tous vos domaines.

content/introduction/deploy/oidc.en.md

@@ -0,0 +1,35 @@
+---
+data: 2024-06-07T20:50:55+02:00
+title: OpenID Connect
+weight: 25
+---
+
+happyDomain supports user authentication via the OpenID Connect protocol. If you have an authentication provider (Auth0, Okta, ...) or Identity Provider (IdP) software such as Keycloak, Authentik, Authelia, ... you can use it with happyDomain, and possibly dispense with the embedded registration and authentication system.
+
+
+## Configuration
+
+To enable OpenID Connect, you'll need to set the following options:
+
+```
+HAPPYDOMAIN_OIDC_PROVIDER_URL=https://auth.example.com/
+HAPPYDOMAIN_OIDC_CLIENT_ID=youClientId
+HAPPYDOMAIN_OIDC_CLIENT_SECRET=0a1b2c3d4e6f7A8B9C0D
+```
+
+The `PROVIDER_URL` setting should be defined to the base URL of your authentication service.
+The service should expose a settings discovery endpoint (at `/.well-known/openid-configuration`).
+
+
+### OpenID Connect provider settings
+
+You'll need to setup a new application in your authentication provider, with the following settings:
+
+- Provider type: OIDC ou OAuth2
+- Grant type: `Authorization Code`
+- Application type: `Web` ou `PWA`
+- Client type: `private`
+- Scopes: `openid`, `profile`, `email`
+
+Also define the allowed callback URL to:
+- `https://yourHappyDomain.example.com/auth/callback`

content/introduction/deploy/oidc.fr.md

@@ -0,0 +1,34 @@
+---
+data: 2024-06-07T20:50:55+02:00
+title: OpenID Connect
+weight: 25
+---
+
+happyDomain supporte l'authentification d'utilisateurs via le protocole OpenID Connect. Si vous avez un prestataire pour l'authentification (Auth0, Okta, ...) ou que vous avez un logiciel dit "Identity Provider" (IdP) tel que Keycloak, Authentik, Authelia, ... vous pouvez l'utiliser avec happyDomain et vous passez, éventuellement, du système d'inscription et d'authentification embarqué.
+
+
+## Configuration
+
+Pour activer l'authentification OpenID Connect, vous aurez besoin de définir les options suivantes :
+
+```
+HAPPYDOMAIN_OIDC_PROVIDER_URL=https://auth.example.com/
+HAPPYDOMAIN_OIDC_CLIENT_ID=youClientId
+HAPPYDOMAIN_OIDC_CLIENT_SECRET=0a1b2c3d4e6f7A8B9C0D
+```
+
+L'option `PROVIDER_URL` correspond à l'URL de base du service d'authentification. Celui-ci doit mettre à disposition une page de découverte de ses paramètres (accessible à `/.well-known/openid-configuration`).
+
+
+### Paramétrage du fournisseur OpenID Connect
+
+Vous aurez besoin de créer une application dans votre fournisseur d'authentification, avec les paramètres suivants :
+
+- Provider type: OIDC ou OAuth2
+- Grant type: `Authorization Code`
+- Application type: `Web` ou `PWA`
+- Client type: `private`
+- Scopes: `openid`, `profile`, `email`
+
+Définissez également une adresse de retour autorisée :
+- `https://yourHappyDomain.example.com/auth/callback`

content/introduction/deploy/ovh.en.md

@@ -0,0 +1,32 @@
+---
+data: 2024-07-15T11:33:09+02:00
+title: OVH API configuration
+weight: 50
+---
+
+In order to manage domains hosted by OVH, an additional configuration step is required.
+
+Authentication to the OVH API works in 2 stages:
+
+1. First, you need to register an ***application*** (e.g. *happyDomain*). An application has an identifier and a secret that must be entered as a happyDomain parameter.
+2. For each OVH account you wish to manage, the happyDomain interface redirects you to the OVH page for creating the *Consumer key*.
+
+The *application* must be created from an existing OVH account, regardless of whether it has domains or not; it is a matter of identifying the person responsible for implementing the designated application.
+Access to account data, and in particular to the domains they manage, is via the *Consumer key*.
+
+For more information, see this page: <https://docs.ovh.com/gb/en/api/api-rights-delegation/#application-registration>
+
+
+## Register your happyDomain instance with OVH
+
+1. Go to <https://api.ovh.com/createApp/>.
+2. Fill in the form with a name and description that reflects the name and use of your application, e.g. *happyDomain*.
+
+Once the form has been validated, you'll get a key and a secret.
+This information must be specified in the happyDomain configuration:
+
+`ovh-application-key`
+: Application key pour l'API d'OVH
+
+`ovh-application-secret`
+: Clef secrète pour l'API d'OVH

content/introduction/deploy/ovh.fr.md

@@ -0,0 +1,32 @@
+---
+data: 2024-07-15T11:33:09+02:00
+title: Configuration pour l'API OVH
+weight: 50
+---
+
+Afin de pouvoir gérer des domaines hébergés par OVH, il est nécessaire de passer par une étape de configuration supplémentaire.
+
+En effet, le principe de fonctionnement de l'authentification à l'API d'OVH se fait en 2 étapes :
+
+1. Tout d'abord il faut enregistrer une ***application*** (par exemple *happyDomain*). Une application dispose d'un identifiant et d'un secret qu'il convient de renseigner en tant que paramètre d'happyDomain.
+2. Pour chaque compte OVH que l'on souhaite gérer, l'interface d'happyDomain redirige vers la page d'OVH permettant de créer la *Consumer key*.
+
+L'*application* doit être créée à partir d'un compte OVH existant, peu importe qu'il dispose de domaines ou non, il s'agit d'identifier la personne responsable de la mise en œuvre de l'application désignée.
+L'accès aux données d'un compte, notamment aux domaines qu'ils gèrent, se fait au travers de la *Consumer key*.
+
+Pour plus d'information, voir cette page : <https://docs.ovh.com/gb/en/api/api-rights-delegation/#application-registration>
+
+
+## Enregistrer votre instance d'happyDomain auprès d'OVH
+
+1. Rendez-vous sur la page <https://api.ovh.com/createApp/>.
+2. Remplissez le formulaire avec un nom et une description qui refléte le nom et l'usage de votre application, par exemple *happyDomain*.
+
+Une fois le formulaire validé, vous obtiendrez une clef et un secret.
+Ces informations sont à indiqué dans la configuration d'happyDomain :
+
+`ovh-application-key`
+: Application key pour l'API d'OVH
+
+`ovh-application-secret`
+: Clef secrète pour l'API d'OVH

content/introduction/deploy/testing.fr.md

@@ -0,0 +1,78 @@
+---
+data: 2023-01-19T18:28:25+02:00
+title: Environnement de test ou unipersonnel local
+weight: 10
+---
+
+Suivez ce guide d'installation si vous souhaitez utiliser happyDomain directement sur votre machine, le plus simplement possible, sans disposer de la gestion d'utilisateurs.
+
+C'est une configuration simple, qui est appropriée pour évaluer happyDomain ou pour l'utiliser sans authentification sur sa propre machine, ou avec une authentification fournie par un reverse proxy.
+
+Vous pouvez le déployer en utiliser Docker ou bien en téléchargeant l'un des exécutables mis à votre disposition. Nous verrons ci-après les deux méthodes.
+
+
+## Via Docker/podman
+
+Si vous être familier de Docker (ou `podman`), vous pouvez disposer d'happyDomain en quelques secondes avec la ligne de commande suivante :
+
+```
+docker container run -e HAPPYDOMAIN_NO_AUTH=1 -p 8081:8081 happydomain/happydomain
+```
+
+Si vous souhaitez rendre les données persistantes, il faut ajouter un volume :
+
+```
+docker volume create happydns_data
+docker container run -v happydns_data:/data -e HAPPYDOMAIN_NO_AUTH=1 -p 8081:8081 happydomain/happydomain
+```
+
+Quelque soit votre choix, rendez-vous ensuite sur <http://localhost:8081> pour commencer à utiliser happyDomain.
+
+
+## Via l'exécutable
+
+1. Commencez par télécharger l'exécutable correspondant à votre architecture de processeur sur : <https://get.happydomain.org/master/>.
+  Les versions `darwin` sont pour MacOS, tandis que les versions `linux` sont pour GNU/Linux. Toutes les versions distribuées sont statiques et devraient fonctionner quelque soit votre libc (GNU libc la plupart du temps, musl pour Alpine, ...).
+
+1. Rendez le binaire que vous avez téléchargé exécutable : `chmod +x happydomain-OS-ARCH`.
+
+1. Exécutez le binaire : `HAPPYDOMAIN_NO_AUTH=1 ./happydomain-OS-ARCH`.
+
+1. Rendez-vous sur <http://localhost:8081/> pour commencer à utiliser happyDomain.
+
+
+## Que font ces options ?
+
+L'option `HAPPYDOMAIN_NO_AUTH=1` est un paramètre qui indique à happyDomain qu'il ne doit pas attendre d'authentification : les domaines sont partagées entre toutes les connexions qui arrivent. En fait, cela va automatiquement créer un utilisateur par défaut et désactiver toutes les fonctionnalités de connexion, d'enregistrement de compte, ...
+
+
+## Peut-on le mettre sur Internet comme ça ?
+
+Non ! Il est primordial que vous n'exposiez pas votre happyDomain sur Internet sans authentification.
+En effet, tout son contenu serait accessible à n'importe qui, et pourrait prendre possession de votre/vos domaines.
+
+Utilisez systématiquement un reverse-proxy tel que nginx, Apache, HAproxy, Treafik, ... en ajoutant une étape de filtrage ou d'authentification basique.
+
+Par exemple, vous pouvez filtrer les IP qui peuvent accéder au service.
+Voici un exemple de configuration pour nginx, filtrant les IP (directive [`allow`](http://nginx.org/en/docs/http/ngx_http_access_module.html)) :
+
+```
+server {
+    listen 80;
+    listen [::]:80;
+
+    server_name happydomain.example.com;
+
+    location / {
+        allow 42.42.42.42;
+        deny all;
+
+        proxy_pass	http://localhost:8081;
+        proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
+    }
+
+}
+
+```
+
+Vous pouvez aussi ajouter une authentification à base de [mot de passe simple](http://nginx.org/en/docs/http/ngx_http_auth_basic_module.html).