myc-manage/README.org

#+SETUPFILE: /home/vaab/dev/el/org-html-themes/setup/theme-readtheorg.setup
#+PROPERTY: Effort_ALL 0 0:30 1:00 2:00 0.5d 1d 1.5d 2d 3d 4d 5d
#+PROPERTY: Max_effort_ALL 0 0:30 1:00 2:00 0.5d 1d 1.5d 2d 3d 4d 5d
#+PROPERTY: header-args:python :var filename=(buffer-file-name)
#+PROPERTY: header-args:sh :var filename=(buffer-file-name)
#+TODO: TODO WIP BLOCKED POSTPONED | DONE CANCELED
#+LATEX_HEADER: \usepackage[margin=0.5in]{geometry}
#+LaTeX_CLASS: article
#+OPTIONS: H:8 ^:nil prop:("Effort" "Max_effort") tags:not-in-toc
#+COLUMNS: %50ITEM %Effort(Min Effort) %Max_effort(Max Effort)

#+begin_LaTeX
  \hypersetup{
    linkcolor=blue,
    pdfborder={0 0 0 0}
  }
#+end_LaTeX

#+TITLE: Architecture 0k.io

#+LATEX: \pagebreak

* Process de déploiement

Description du process de déploiement pour une nouvelle installation

** Base myc

*** Qu'est ce c'est ?

A partir d'une debian 9 ou debian 10, on peut installer la machine
pour être prête à utiliser un déploiement myc.

Une fois executé, la machine aura toute les deps pour lancer une
commande compose qui fera peut-être appel à des registry de
mycéliandre. Un compose de base est aussi proposé.

*** Déploiement

**** Hôte linux base debian 9 et debian 10

***** Accès ssh standardisé

Via la commande =0km=, depuis votre poste, permet de standardiser
l'accès avec vos clés SSH, et positionner le nom de domaine si
nécessaire.

#+BEGIN_SRC sh
0km vps-setup HOST
#+END_SRC

Note: ceci fonctionnera que si vous avez un fichier de configuration
dans =/etc/0km/config.yml= (si vous allez l'utiliser en root) ou dans
=~/.config/0km/config.yml= autrement. Ce fichier doit au moins contenir
une clé ssh (ou plusieurs) ainsi:

#+begin_src yaml
ssh-access:
  public-keys:
    - ssh-rsa AAAAB3NzaC1yc2EAAAAD...qGy20KlAOGPf nom_clef
#+end_src


***** Déploiement de la solution pour compose

Depuis le VPS, en root:

#+BEGIN_SRC sh
export WITHOUT_DOCKER_CLEAN=1  ## only if you want to remove docker clean from cron
wget https://justodooit.myceliandre.fr/r/deploy -qO - | bash
#+END_SRC

Si vous souhaitez positionner le nom de domaine:

#+BEGIN_SRC sh
export WITHOUT_DOCKER_CLEAN=1  ## only if you want to remove docker clean from cron
export DOMAIN=myhost.com
wget https://justodooit.myceliandre.fr/r/deploy -qO - | bash
#+END_SRC

***** Déploiement de la solution pour mailcow

****** Sur un vps sans mailcow de pre-installé

#+BEGIN_SRC sh
export WITHOUT_DOCKER_CLEAN=1  ## only if you want to remove docker clean from cron
wget https://justodooit.myceliandre.fr/r/deploy -qO - | bash
#+END_SRC

****** Sur un vps avec mailcow de pre-installé


#+BEGIN_SRC sh
export WITHOUT_DOCKER_CLEAN=1  ## only if you want to remove docker clean from cron
export NO_DOCKER_RESTART=1 ## Can use that only if mailcow is pre-existing 
wget https://justodooit.myceliandre.fr/r/deploy -qO - | bash
#+END_SRC

**** Hôte macosx

- install bash, docker
- Uncheck "Securely store docker logins in macOS keychain"


*** Ce que cela fait
**** Mettre la machine en état charm-ready

- installation du strict minimu pour lancer les =charms=

- téléchargement de la dernière version des =0k-charms= (collection
  de recettes d'installation et de gestion de docker)

**** Mettre la machine en état compose ready (notre docker qui va bien)

via le lancement du charm =docker-host= qui installe:

  - docker, docker-compose, compose avec des versions qui vont bien
  - paquets maisons (kal-scripts, 0k-manage, 0k-pgm, lxc-scripts, 0k-docker)
  - accès pour le repository deb de kalysto.org
  - clé SSH pour repos git.kal.fr
  - login sur le docker registry docker.0k.io

**** Commandes spécifique à myc

- login sur le registry myc
- téléchargement du compose de base dans =/opt/apps/myc-deploy=


** Modification du compose

*** Qu'est-ce que c'est ?

Il y a des update client à faire souvent sur le compose. Cette étape
doit être externalisée au plus possible, sont consigné ici ce qu'il
faut encore faire à la main.

*** Commande

**** Création de clé OVH pour letsencrypt/lexicon

Ceci n'est nécessaire qu'en cas d'utilisation de la méthode DNS
pour valider la possession du domaine auprès de letsencrypt.

#+BEGIN_SRC shell
APPLICATION_KEY=XXXXXXXXXXXXXXXXX
REDIR_WEBSITE=https://0k.io

req=$(cat <<EOF
{
    "accessRules": [
        {
            "method": "GET",
            "path": "/*"
        },
        {
            "method": "POST",
            "path": "/*"
        },
        {
            "method": "PUT",
            "path": "/*"
        },
        {
            "method": "DELETE",
            "path": "/*"
        }
    ],
    "redirection":"$REDIR_WEBSITE"
}
EOF
)
res=$(curl -X POST \
     -H "X-Ovh-Application: ${APPLICATION_KEY}" \
     -H "Content-type: application/json" \
     https://eu.api.ovh.com/1.0/auth/credential \
     -d "$req")
consumer_key=$(echo "$res" | jq -r .consumerKey)
validation_url=$(echo "$res" | jq -r .validationUrl)
echo "Visit: $validation_url"
echo "ConsumerKey: $consumer_key"
#+END_SRC

Il s'agit alors de remplir le compose.yml

#+BEGIN_SRC yaml
    ovh:
      ## see: https://api.ovh.com/g934.first_step_with_api
      entrypoint: ovh-eu
      application:
        key: XXXXXXXXXXXXXXXX
        secret: YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
      consumer_key: ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
#+END_SRC

Puis de valider que tout est ok:

#+BEGIN_SRC shell
check-compose-ovh-credentials compose.yml
#+END_SRC


** Lancement/Deploy de service odoo

*** Qu'est ce que c'est ?

A partir d'une base myc, cette commande permet d'envoyer la
construction et l'assemblage de tous les services décrit dans le
=compose.yml= fourni par défaut.

*** commandes

#+BEGIN_SRC sh
cd /opt/apps/myc-deploy
compose --debug up odoo frontend
#+END_SRC

De manière générale:

#+BEGIN_SRC sh
compose [--debug] up [SERVICES...]
#+END_SRC

*** Ce que ça fait

Les charms vont s'occuper de séparer la config des
donnée, de tout stocker dans =/srv/datastore=, il vont
s'occuper de la petite maintenance:

- le charm postgres (qui est une dépendance du service odoo) va créer
  un mot de passe et le filer à odoo
- le charm apache (qui implémente le service frontend)
  va créer les fichiers de conf apache pour déclarer un virtualhost
  et mettre les clés SSL s'il y a lieu.


* Gestion

Description des process de gestion d'une installation existante.

** Connection aux serveurs


*** installation commande =st=

Le mieux est d'utiliser la commande =st= que l'on peut installer ainsi
sur un poste linux ayant =apt=:

Se mettre en =root=:

#+begin_src sh
cat <<'EOF' > /usr/local/bin/st
#!/bin/bash

echo "Trying mosh to $1"
TERM=xterm-256color mosh "$1" -- bash -c "tmux attach || { tmux; }"
if [ "$?" == "5" ]; then
  echo "Fallback to ssh $1"
  ssh "$1" -tM "TERM=xterm-256color tmux attach || TERM=xterm-256color tmux"
fi
EOF
chmod +x /usr/local/bin/st
apt install mosh
#+end_src

*** utilisation de la commande =st=

=st= utilise =ssh= ou =mosh= et se met dans un =tmux= sur la destination.

#+begin_src sh
st root@monvps.fr
#+end_src

On note qu'il faut penser à mettre les clé SSH sur la destination.

** Mise à jour de l'ensemble

Pour mettre à jour un VPS:

#+BEGIN_SRC sh
myc-update
#+END_SRC

Cette commande va ré-appliquer l'installation du charm =docker-host=
qui installe ou met à jour chaque composant.

** Gestion des dockers
*** Relancement

si on veut relancer parce que le compose a changé :

on fait pareil qu'au lancement : lors du "up", docker-compose se
rend compte que la définition des services a changé et relance les
docker voulu.

*** Arrêt

#+BEGIN_SRC sh
compose --debug down
#+END_SRC

*** Voir les logs

#+BEGIN_SRC sh
cd /opt/apps/myc-deploy
compose --debug logs odoo
#+END_SRC

*** Obtenir les IPs des dockers

#+BEGIN_SRC sh
docker-ip
#+END_SRC

*** Limiter la mémoire utilisée par un container

Certains container vont demander beaucoup de memoire par défaut et
doivent être contenu dans des environment limités.

Aussi, on peut limiter la mémoire d'un docker dans le fichier
=compose.yml=:

#+begin_src yaml
  mon-service:
    # ...
    docker-compose:
      mem_limit: 2g
      memswap_limit: 2g  ## Au cas où l'on a du swap
    # ...
#+end_src


*** Vérification de santé générale

La commande =vps check-fix= contrôler les containers en cours de
fonctionnement pour vérifier s'ils ne sont pas touché par quelques
problème identifiés et connus. Et elle va réparer ce qu'elle peut.

#+begin_src sh
vps check-fix
#+end_src

Il est possible de lancer ces vérifications sur une liste de service
spécifique ou de sélectionner le test voulu. Voir =vps check-fix
--help= pour plus d'info.

Il peut être opportun d'ajouter dans sur l'hôte, par exemple, une
vérification périodique et automatique:

#+begin_src sh
cat <<EOF > /etc/cron.d/vps-check
SHELL=/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin

*/15 * * * *   root   vps check-fix -s -c container-aliveness 2>&1 | logger -t check-fix

*/5 * * * *    root   vps check-fix -s rocketchat 2>&1 | logger -t check-fix
EOF
#+end_src


** Par services

*** odoo
**** Backups
***** Backuping odoo account (filestore and database)
****** Via =vps= command

A few examples:

#+begin_src sh
## dump default database of default service to file db.zip
vps odoo dump db.zip

## dump default database of 'odoo2' service
vps odoo dump /tmp/db.zip -s odoo2

## dump 'odoodev' database of default 'odoo' service
vps odoo dump /tmp/db.zip -d odoodev
#+end_src

****** Via charm only actions

Be sure that your odoo instance should be already up.

#+BEGIN_SRC sh
MYODOOSERVICENAME=odoo
DBNAME="$MYODOOSERVICENAME"
OUTPUTFILE=backup-odoo.zip
compose save "$MYODOOSERVICENAME" "$DBNAME" > "$OUTPUTFILE"
#+END_SRC

***** Restoring odoo account (filestore and database)

*IMPORTANT* you might want to consider the usage of =docker-cutoff= if
you are restoring a production odoo onto a dev or staging odoo that you
don't want to allow to go mess around with sending mails or fetching mails.

#+BEGIN_SRC yaml
docker-cutoff 25 993 465
#+END_SRC

****** Via =vps= command

#+begin_src sh
## restore default database of default service from file db.zip
vps odoo restore db.zip

## restore default database of 'odoo2' service
vps odoo restore /tmp/db.zip -s odoo2

## restore 'odoodev' database of default 'odoo' service
vps odoo restore /tmp/db.zip -d odoodev
#+end_src

****** Via standard charm action

Be sure that your odoo instance is already up.

These are the normal loading instructions:

#+BEGIN_SRC sh
MYODOOSERVICENAME=odoo
DBNAME="$MYODOOSERVICENAME"
SOURCEFILE=backup-odoo.zip
compose load "$MYODOOSERVICENAME" "$DBNAME" < "$SOURCEFILE"
#+END_SRC

**** Update de modules

#+BEGIN_SRC sh
compose update odoo MABASE [MODULE [MODULE ...]]
#+END_SRC


**** lancement d'une commande odoo

Si l'ensemble n'est pas up:

#+BEGIN_SRC sh
compose --debug run odoo --help
#+END_SRC


**** Mod dev d'odoo

Il est souhaitable de lancer odoo en mode dev avec un terminal prêt à
accueillir un pdb par exemple, et pouvoir changer facilement la ligne de commande.

On peut tout a fait lancer odoo directement, par exempe:

#+BEGIN_SRC sh
compose run --rm --use-aliases odoo --dev=wdb --config=/opt/odoo/auto/odoo.conf
#+END_SRC

On récupère ainsi tous les volumes et autres options (sauf ce qui est
dans =command:=) défini dans =compose.yml=.

Un problème cependant: si on utilise apache comme frontend, celui-ci
ne pourra pas résoudre le nom =odoo= à cause de problèmes autour de
=docker-compose= et/ou =docker network=. En effet, si on fait un =up=
comme d'habitude, et qu'on souhaite simplement arrêter le service
classique pour ensuite le remplacer par la commande au dessus, cela ne
fonctionnera pas.  En effet, l'alias réseau =odoo= n'est plus adjoignable
(même avec les commandes =docker network {dis,}connect=), et même si
le container original de odoo est détruit ou éjecté du réseau, ou que l'on
essaye de connecter soi-même le nouveau container.

Un moyen (bancal) de passer outre cependant:
- =down= pour fermer le réseau
- =create= sur le service apache, puis =restart=.
- enfin, le =run= tel que décrit au dessus

Soit:

#+BEGIN_SRC sh
compose down &&
compose create apache &&
compose restart apache &&
compose run --rm --use-aliases odoo --dev=wdb --config=/opt/odoo/auto/odoo.conf
#+END_SRC

Le container odoo crée par la dernière ligne se retirera proprement des tables DNS
interne, et donc peut tout a fait être relancée autant de fois que l'on souhaitera.

**** Single Sign On en carafe

L'installation du module =website= et =galicia= pour l'authentication
Single Sign On peut aboutir à une situation où le sign on est
automatique et arrive sur un mauvais utilisateur.

Il s'agit de l'utilisateur attaché à l'objet =website= surlequel le sign on
du service tiers a été configuré pour pointer.

En effet, l'objet ~website~ possède un ~user_id~ qui va être utilisé en guise
d'utilisateur par défaut. Si celui-ci ne correspond pas à l'utilisateur odoo ~public_user~,
alors =galicia= considère que cet utilisateurs est déjà loggé et offre son accès.

La solution est de forcer le ~user_id~ des objets ~website~ à l'id de l'utilisateur ~public_user~.

C'est ce que fait la commande:

#+begin_src sh
vps odoo fix-sso
#+end_src

*** letsencrypt

Le service letsencrypt fourni des certificat SSL à la demande et les
renouvelle automatiquement.

**** configuration dans compose
***** Authentification HTTP

Il n'y a besoin d'aucune option dans le service =letsencrypt=.

Le charm =apache= doit trouver un service utilisant le charm =letsencrypt=, cette
connection se fera automatiquement si un servce de type =letsencrypt= est lancé soit
parce que directement mentionné dans la racine ou dans une relation explicite.

La relation construite automatiquement (ou manuellement) d'un service
=apache= vers un service =letsencrypt= s'appelle =cert-provider=.

Une fois que ce service est relié à apache, on peut s'en servir comme clé dans
la configuration =ssl= des relations =*-->web-proxy-->apache=.

Par défaut, =apache= utilisera du ssl pour tout se virtual-host s'il trouve un
=cert-provider= à disposition.

Aussi la configuration suivante est suffisante pour avoir un site publié en SSL:
#+BEGIN_SRC yaml

www.mydomain.org:
  charm: odoo

apache:

letsencrypt:

#+END_SRC


Cela équivaut à :


#+BEGIN_SRC yaml

www.mydomain.org:
  charm: odoo
  relations:
    web-proxy:
      myapache:
        domain: www.mydomain.org
        ssl:
          myletsencrypt:
            challenge-type: http

myapache:
  charm: apache

myletsencrypt:
  charm: letsencrypt

#+END_SRC



***** Authentification DNS
****** créer un nouveau jeu de clé OVH pour l'authentification DNS

  When =letsencrypt= is setup and running::

  #+BEGIN_SRC sh
  compose --debug add letsencrypt DOMAIN [DOMAIN...]
  #+END_SRC

  Exemple de setup (dans =compose.yml=):

  #+BEGIN_SRC yaml
  letsencrypt:
    options:
      email: admin@0k.io
      ovh:
        entrypoint: ovh-eu
        application:
          key: ZZZ
          secret: XXX
        consumer_key: YYYYY
  #+END_SRC

  Le résultat est dans =/srv/datastore/data/letsencrypt/etc/letsencrypt/live/DOMAIN1=
  Il apparaît entre 30sec et 1 minute après la demande.

****** Vérifier que le jeu de clé ovh est bon

  Cette commande prend le compose yml et va vérifier que les accès sont valides:

  #+BEGIN_SRC shell
  check-compose-ovh-credentials compose.yml
  #+END_SRC

**** Utilisation manuelle

On peut utiliser le service =letsencrypt= manuellement

***** creation d'un certificat http

#+BEGIN_SRC shell
compose crt letsencrypt create DOMAIN [DOMAIN...]
#+END_SRC

Cette action crée un certificat (et force le renouvellement si existant).

On peut y injecter une configuration via =--add-compose-content= si nécessaire::

#+BEGIN_SRC shell
compose --add-compose-content='
letsencrypt:
  ovh:
    ## see: https://api.ovh.com/g934.first_step_with_api
    entrypoint: ovh-eu
    application:
      key: XXX
      secret: YYY
    consumer_key: ZZZ
  challenge-type: dns
  #renew-before-expiry: 30' crt letsencrypt create DOMAIN [DOMAIN...]
#+END_SRC

***** Renew de tous les certificats

Cela renew uniquement les certificats dont la date de validité est inférieure à 30j

#+BEGIN_SRC shell
compose crt letsencrypt renew
#+END_SRC


***** Liste des certificats gérés et infos connexes

#+BEGIN_SRC shell
compose run letsencrypt crt list
#+END_SRC

***** suppression d'un certificat

#+BEGIN_SRC shell
compose run letsencrypt certbot delete --cert-name DOMAIN
#+END_SRC

*** apache

**** Utiliser letsencrypt

Pour ajouter la fonctionalité de génération automatique de certificat
 via le service =letsencrypt=, il faut:
- déclarer un service =letsencrypt= si cela n'est pas déjà fait
- le lier au charm apache via une relation =cert-provider=:

#+BEGIN_SRC yaml
frontend:
  charm: apache
  relations:
    cert-provider: letsencrypt

letsencrypt:
  ...
#+END_SRC

Et l'on peut alors utiliser la valeur =letsencrypt= (le nom du service qui implémente
qui est en relation =cert-provider= avec apache) dans le champ =ssl=::

#+BEGIN_SRC yaml
  web-proxy:
    apache:
      ...
      ssl: letsencrypt
#+END_SRC

**** Changer les clés SSL

Voici un exemple de ce qu'on peut mettre dans les options de la relation apache
pour déclarer le certificat que l'on souhaite:

#+BEGIN_SRC yaml

  ssl:
    ca-cert:
      -----BEGIN CERTIFICATE-----
      MIIF6TCCA9GgAwIBAgIQBeTcO5Q4qzuFl8umoZhQ4zANBgkqhkiG9w0BAQwFADCB
      iDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0pl
      ...
      m9T8bJUox04FB6b9HbwZ4ui3uRGKLXASUoWNjDNKD/yZkuBjcNqllEdjB+dYxzFf
      BT02Vf6Dsuimrdfp5gJ0iHRc2jTbkNJtUQoj1iM=
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      MIIFdzCCBF+gAwIBAgIQE+oocFv07O0MNmMJgGFDNjANBgkqhkiG9w0BAQwFADBv
      MQswCQYDVQQGEwJTRTEUMBIGA1UEChMLQWRkVHJ1c3QgQUIxJjAkBgNVBAsTHUFk
      ...
      Le9Gclc1Bb+7RrtubTeZtv8jkpHGbkD4jylW6l/VXxRTrPBPYer3IsynVgviuDQf
      Jtl7GQVoP7o81DgGotPmjw7jtHFtQELFhLRAlSv0ZaBIefYdgWOWnU914Ph85I6p
      0fKtirOMxyHNwu8=
      -----END CERTIFICATE-----
    cert: |
      -----BEGIN CERTIFICATE-----
      MIIF/TCCBOWgAwIBAgIRALUydpTpCApfYMuJchDJv5AwDQYJKoZIhvcNAQELBQAw
      XzELMAkGA1UEBhMCRlIxDjAMBgNVBAgTBVBhcmlzMQ4wDAYDVQQHEwVQYXJpczEO
      ...
      lIxY9HJanHrWvjiz7+eToxXpZJtAPXTx5hxzcJrtWROlq7IJCMIhzr/EVA37jTCk
      Xs5S6mr0T6Dqx6MQkPATSsEEJlLH5wq3DxXQcrMqnM/WHMRYUCkoTl37sXplflHe
      jw==
      -----END CERTIFICATE-----
    key: |
      -----BEGIN PRIVATE KEY-----
      MIIJRQIBADANBgkqhkiG9w0BAQEFAASCCS8wggkrAgEAAoICAQDONqqTCS4CiSi/
      XeNpp2nUsq1299spGc7mlRs+PDrXNHscB5lUB5/yo2yEetYXrJacQ8n4NV9hkID5
      ...
      44eHDYsofcnRbidGR+QT8PQgiiDNCkbpi2u4QnLTs0w4oW+53ZTyHYEYF2rcLbIb
      vRt4kR4KG6ULXrmsRA4WQjBDJ9vZw2aK+w==
      -----END PRIVATE KEY-----

#+END_SRC

**** Ajouter des rêgles particulière de apache


#+BEGIN_SRC yaml
    relations:
      web-proxy:
        apache:
          ...
          apache-custom-rules: |
            RewriteEngine On
            RewriteCond %{HTTPS} off
            RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [R=302,L,QSA]

#+END_SRC

**** Vérification des derniers logs de renouvellement automatique

#+BEGIN_SRC shell
tail -f /srv/datastore/data/cron/var/log/cron/letsencrypt-renew_script.log -n 200
#+END_SRC


*** postgres

**** utilisation de pgm

récupérer l'IP du docker postgres via =docker-ip=

#+BEGIN_SRC sh
PGHOST=172.19.0.2 PGUSER=postgres pgm ls
#+END_SRC


**** base corrompue, réparation

Il s'agit de lancer un =pg_resetwal=, il faut veiller à plusieurs élément:
- bien arréter tout process utilisant le répertoire de =data= du
  postgres en question, généralement un =compose stop postgres=
  suffit.
- utiliser l'image du postgres via son nom (habituellement =myc_postgres=).
- monter le répertoire data =directement=

Le tout peut se faire ainsi dans une installation qui fait tourner un postgres 
actuellement:

#+begin_src sh
compose stop postgres &&
docker run --rm --entrypoint pg_resetwal \
    -u postgres -v /srv/datastore/data/postgres/var/lib/postgresql/data:/var/lib/postgresql/data \
    myc_postgres \
    /var/lib/postgresql/data &&
docker start myc_postgres_1
#+end_src


*** mysql

**** sur installation mailcow

Le script =vps= fourni via =myc-manage=, permet la commande =vps
install backup MYBACKUPDEST=, qui s'occupe de mettre en place le dump
de =mysql=, et le système pour envoyer les backup régulièrement via
rsync.

**** docker sans compose

#+begin_src sh
export MYSQL_ROOT_PASSWORD=xxx
export MYSQL_CONTAINER=mailcowdockerized_mysql-mailcow_1

/srv/charm-store/mysql/hooks/install.d/60-backup.sh
#+end_src


*** rsync-backup

**** Installation du backup de compose / mailcow

Les commandes suivantes permettent l'installation du backup sur les
deux type de serveur suivant :
- un serveur =compose= est un serveur ayant des services géré par
 =compose= à backupper.
- un serveur =mailcow= est un serveur faisant tourner l'installation =mailcow=.


***** Via la commande 0km sur un hôte admin

L'instruction suivante doit être executée sur un hôte ayant la
commande =0km= d'installée et les accès SSH vers le VPS et un compte
d'administration du service =rsync-backup-target= sur le serveur
d'archivage.

Dans l'exemple suivant on utilise le compte administration du service
=rsync-backup-target= nommé =myadmin=... pour avoir la liste des
compte admin, se reporter au contenu du fichier =compose.yml= sur le
serveur d'archivage et plus spécifiquement la configuration du service
=rsync-backup-target=. Les noms des comptes admin y sont défini ainsi
que les clés publiques y ayant accès.

#+begin_src sh
0km vps-install backup myadmin@core-06.0k.io:10023 myvps.fr
#+end_src

Note: on peut spécifier autant de vps que l'on souhaite en fin de
ligne de commande.  L'installation des vps se fera en parallèle et
vers le serveur d'archive spécifié en premier argument.

Note: cette commande peut-être executé plusieurs fois sur le même
hôte : si tout est déjà installé, cette commande n'aura pour seul
effet que de relancer une synchronisation vers le backup.


***** Via la commande vps sur le vps lui-même

A faire depuis le serveur compose ou mailcow:

#+begin_src sh
vps install backup core-06.0k.io:10023
#+end_src

Ici =core-06.0k.io:10023= est le serveur cible d'archivage (à modifier
si nécessaire).

A la fin de l'opération, une commande est proposée pour ajouter
facilement la nouvelle clé à l'hôte s'occupant de l'archivage.

Cette commande doit être executée sur un hôte ayant les accès vers un
compte administration du serveur d'archivage.

Dans le cas d'un VPS sur installation compose, il s'agira également de
relancer sur le VPS lui-même, un =compose up= pour intégrer et lancer
le nouveau container de backup.

Une fois la clé enregistrée du coté du serveur d'archivage, un premier
archivage peut être déclenché via:

#+begin_src sh
vps backup
#+end_src

Ceci permet de lancer le premier backup et de valider que tout fonctionne


**** Installation du backup sur un host debian

Cela fonctionnera sur tout host ayant une base debian.

#+begin_src sh
DOMAIN=mail.xxxx.fr
BACKUP_SERVER=core-06.0k.io:10023

cd /srv/charm-store/rsync-backup/
./hooks/install.d/60-install.sh

#+end_src

Note, il est possible de spécifier des exclusions pour chaque
répértoire mirroré de telle façon:

#+begin_src sh
cat <<EOF >> /etc/mirror-dir/config.yml
/home:
  exclude:
  - /*/.cache/
  - /*/.gvfs/
  - /*/.local/share/Trash/files/
  - /*/.Trash/
  - /*/.mozilla/firefox/*/Cache/
  - /*/.mozilla/firefox/*/storage/default/*/cache/
/media/data:
  exclude:
  - /binary/games/_steam
  - /incoming
  - /.Trash*
  - /lost+found
  - /backup/device
EOF
#+end_src


*** nextcloud
**** Mise à jour en dernière version

Cette commande permet d'appliquer successivement les version de
nextcloud, elle modifie le =compose.yml=. Et installe la dernière
version disponible donnée par =docker-tags-fetch docker.0k.io/nextcloud=.

Étant donné que la commande est un peu nouvelle et la tâche assez
fastidieuse et risquée, ne pas hésiter à la lancer dans un =tmux= pour
être prêt à demander de l'aide. Également, lancer un =myc-update= avant.

Aussi, il est toujours bon de vérifier que le backup fonctionne et que
la version sur le serveur de backup est à jour (lancer =vps backup= est
un bon moyen de voir cela).

#+begin_src sh
  vps nextcloud upgrade
#+end_src
*** onlyoffice
**** Troubleshooting

Il y eu de nombreux cas où onlyoffice pète ses propres
fichiers de config. Une bonne façon de le régler:

#+begin_src sh
docker stop myc_onlyoffice_1
rm -rf /srv/datastore/config/onlyoffice
compose --debug up
#+end_src

Ceci permet d'effacer la config mise en place par compose et de la
reconstruire, et tout ce qui est dans
`/srv/datastore/config/onlyoffice` se reconstruit tout seul via les
charms au moment du `compose up`.



* Interventions avancées

Description des process avancés d'intervention sur une installation existante.

** Modification du compose

Y a un exemple en commentaire dans le =/opt/apps/myc-deploy/compose.yml=

Petit exemple:

#+BEGIN_SRC yaml
odoo:
  ...

  docker-compose:
    ## Important to keep as a list: otherwise it'll overwrite charm's arguments.
    command:
      - "--log-level=debug"
    environment:
      TOTO: TUTU
    image: masuperimage

#+END_SRC

** Récupération de donnée

*** Depuis le VPS backuppé

Les VPS backuppés peuvent avoir besoin de récupérer les données
archivées. Pour le moment, comme il n'y pas d'accès aux versions
précédentes des backups, l'intérêt de cette fonctionnalité reste
limité.

**** Par répertoire

Via la commande =vps=, l'action =recover-target= permet de recouvrir
les données du service d'archivage (si celui-ci à été correctement
installé avec les commandes spécifiée dans la [[*rsync-backup][section =rsync-backup=]]).

Récupération d'un répertoire:

#+begin_src sh
vps recover-target "cron/" /tmp/cron
#+end_src

Cette commande va récupérer le contenu archivé dans "cron/" pour le mettre
sur l'hôte courant dans "/tmp/cron".

Il est possible de spécifier l'option =--dry-run= (ou =-n=) pour ne
rien modifier et voir quels sont les actions qui seront menées.

Attention à l'usage de cette commande, en effet le répertoire de
destination peut-être entièrement modifié : cette commande effacera et
modifiera le contenu du répertoire de destination.


*** Depuis un hôte d'administration

**** Récupération d'un VPS complet

Depuis un hôte d'adminstration, et via la command =0km=, nous
pouvons re-déployer un backup existant sur un nouveau VPS.

#+begin_src sh
0km vps-backup recover myadmin@core-06.0k.io:10023#mail.mybackupedvps.com mynewvps.com
#+end_src

Attention, cela supprimera toute installation =mailcow= précédente
(donnée comprise) sur le VPS de destination.

**** Récupération partielle

***** Récupération d'un répertoire ou fichier précis

Depuis un hôte d'adminstration, et via la command =0km=, nous pouvons
récupérer un répertoire ou un fichier précis d'un backup existant sur
un nouveau VPS.

C'est la même commande que pour la récupération complète, on rajoute à
la source un chemin et possible aussi à la destination.

#+begin_src sh
0km vps-backup recover myadmin@core-06.0k.io:10023#mail.mybackupedvps.com:/mon/chemin mynewvps.com
0km vps-backup recover myadmin@core-06.0k.io:10023#mail.mybackupedvps.com:/mon/chemin mynewvps.com:/ma/dest
#+end_src

***** Récupération d'un composant

Suivant si le type de backup est reconnu et le supporte, il est
possible de nommer un composant précis en lieu et place d'un
répertoire ou d'un fichier.

Par exemple, les backup de type 'mailcow' supportent les composants
suivants: =mailcow=, =postfix=, =rspamd=, =redis=, =crypt=, =vmail=,
=vmail-attachments=, =mysql=.

#+begin_src sh
0km vps-backup recover myadmin@core-06.0k.io:10023#mail.mybackupedvps.com:mailcow,mysql mynewvps.com
0km vps-backup recover myadmin@core-06.0k.io:10023#mail.mybackupedvps.com:postfix mynewvps.com
#+end_src


** Troubleshooting

S'il semble qu'il y a un soucis, il est possible de visualiser le
=docker-compose.yml= qui est généré à la fin via l'ajout de =--debug=
AVANT la commande:

#+begin_src sh
compose --debug up odoo frontend
#+end_src

*** en cas de soucis important ou inédit

**** Lancer un ~compose --debug up~

La simple action de relancer un ~compose --debug up~ permet à compose
de repasser sur tous les scripts et notamment cela permet de recréer
toutes les configurations, aussi certains des containers peuvent être
également recréés et relancés. Notamment si de nouvelles images de
services ont été ~pull~ récemment.

#+begin_src sh
compose --debug up
#+end_src

Si cette commande ne fonctionne pas, prendre le temps de bien lire le
message d'erreur.

**** Vider les cache de ~/var/cache/compose~

En cas de problème non expliqués et inédits, il est bon de vérifier si
l'effacement des caches de compose ne permet pas de corriger le
problème :

#+begin_src sh
rm /var/cache/compose/*
#+end_src

Puis relancer la commande qui ne fonctionne pas (par exemple ~compose
--debug up~).

**** Redémarrage du service =docker=

Il y a de nombreux bugs répertoriés sur ~docker~ qui n'ont pas été
réglés depuis de nombreuses années qui sont corrigés par un ~restart~ de
tous les containers et du service docker lui-même.

#+begin_src sh
systemctl restart docker.service
#+end_src

va redémarrer le service docker sur la machine et donc tous les
services gérés par docker (tous les services en somme).

La coupure de service de cette commande est relativement courte
(inférieure à la minute).

**** Redéploiement des services

Ce dernier cas est long, et n'est pas souvent efficace, mais il peut
l'être dans certains cas. Cela va stopper et effacer tous les
containers des services, puis reconstruire toute leur configuration et
les relancer.

Attention cela engendre une coupure de service qui peut être longue (le temps
d'un ~compose up~ complet).

#+begin_src sh
compose --debug down &&
compose --debug up
#+end_src


* Comment ça marche

La surcouche =compose= a pour responsabilité de:
- créer graduellement un =docker-compose.yml= et lancer =docker-compose=.
  - à partir des *charms* qui factorisent les parties réutilisables
  - et à partir du =compose.yml= qui offre une interface plus haut niveau
    et permet d'exprimer plus succintement les intentions de déploiement sans
    entrer dans la logique technique de l'implémentation des services.
- lancer des executable et des instructions au fur et à mesure si nécessaire.

Il part du =compose.yml= et accède aux définitions en yaml des charms
à déployer et qui sont dans /srv/charms ... (qui en fait sont dans
=/opt/apps/0k-charms=).

Chaque charm possède une définition générale (le =metadata.yml=) qui
permet également l'injection d'élément dans le =docker-compose.yml=
final.

Et puis il y a des =hooks= : des scripts bash lancés avec des
information contextuelle dans des variables d'environment, et qui vont
généralement mettre en place des services à l'initialisation ou pour
s'assurer de la bonne liaison entre les services.