From 3ead5c92b8d7d9e08b311d734eb370e9d435fa2e Mon Sep 17 00:00:00 2001 From: Pierre-Olivier Mercier Date: Thu, 19 Jan 2023 19:40:37 +0100 Subject: [PATCH] Add some content under the deploy part --- content/deploy/_index.en.md | 8 +++- content/deploy/_index.fr.md | 5 +++ content/deploy/docker.en.md | 72 +++++++++++++++++++++++++++++++++ content/deploy/testing.fr.md | 78 ++++++++++++++++++++++++++++++++++++ 4 files changed, 162 insertions(+), 1 deletion(-) create mode 100644 content/deploy/docker.en.md create mode 100644 content/deploy/testing.fr.md diff --git a/content/deploy/_index.en.md b/content/deploy/_index.en.md index ba801e9..ccda2a6 100644 --- a/content/deploy/_index.en.md +++ b/content/deploy/_index.en.md @@ -1,7 +1,6 @@ --- date: 2021-01-12T21:38:49+02:00 title: Installation and deployment -author: Frederic chapter: true weight: 40 --- @@ -9,3 +8,10 @@ weight: 40 # Installation and deployment of happyDomain --- + +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 %}} diff --git a/content/deploy/_index.fr.md b/content/deploy/_index.fr.md index 4ad9498..a6c7189 100644 --- a/content/deploy/_index.fr.md +++ b/content/deploy/_index.fr.md @@ -9,4 +9,9 @@ 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 %}} diff --git a/content/deploy/docker.en.md b/content/deploy/docker.en.md new file mode 100644 index 0000000..9b7cce9 --- /dev/null +++ b/content/deploy/docker.en.md @@ -0,0 +1,72 @@ +--- +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 +``` + +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 +``` + +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 +``` + +## 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. diff --git a/content/deploy/testing.fr.md b/content/deploy/testing.fr.md new file mode 100644 index 0000000..25ef303 --- /dev/null +++ b/content/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 pour commencer à utiliser happyDomain. + + +## Via l'exécutable + +1. Commencez par télécharger l'exécutable correspondant à votre architecture de processeur sur : . + 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 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).