stats/README.md

# Service stats.chalec.org

Service de statistiques/métriques de Chalec basé sur le logiciel libre StatoolInfos : https://forge.devinsy.fr/devinsy/statoolinfos.  

Responsable : Christian Momon (@cpm)  

Anciens responsables : n/a.

Ce service s'articule en deux parties :
- côté serveur :
  - un fichier properties décrit le Chalec,
  - une moulinette collecte des fichiers properties et s'en sert pour générér le site web,
- côté services Chalec :
  - un fichier properties décrivant le service,
  - un fichier properties de métriques contenant les statistiques du services,
  - un programme lancé quotidiennement pour compléter le fichier properties de métriques.

Pour déployer StatoolInfos sur un service Chalec, aller directement à la [section dédiée](https://git.a-lec.org/a-lec/commissions/chalec/stats/-/blob/main/README.md#ajout-dun-nouveau-service) de la documentation.


# Installation basique du site web

Actuellement, le site web est statique et généré par la moulinette `statoolinfos` toutes les heures.

Installer les paquets :
```
apt-get install nginx python3-certbot-nginx
```

Ouvrir les ports http (80) et https (443) :
```
ufw allow 'Nginx HTTP'
ufw allow 'Nginx HTTPS'
```

Configurer a minima le site web dans `/etc/nginx/sites-available/stats.chalec.org` :
```
server
{
    listen 80;
    listen [::]:80;

    server_name stats.chalec.org; 

    access_log /var/log/nginx/stats.chalec.org-access.log;
    error_log /var/log/nginx/stats.chalec.org-error.log;
}
```

Activer la configuration :
```
cd /etc/nginx/sites-enabled/
ln -s ../sites-available/stats.chalec.org
```

Vérifier que c'est bon et recharger :
```
nginx -t && systemctl reload nginx
```

Configurer le certificat SSl : 
```
certbot --nginx 
```

Créer un fichier générique `/etc/nginx/statoolinfos.conf` qui sera includé plus tard :
```
   location /.well-known/statoolinfos/ 
   {
       charset utf-8;
       types 
       {
            text/plain    properties;
       }

       alias /srv/statoolinfos/well-known/statoolinfos/;
       autoindex on;
   }
```

Mettre beau le fichier `/etc/nginx/sites-enabled/stats.chalec.org` :
``` 
server
{
    listen 80;
    listen [::]:80;

    server_name stats.chalec.org;

    access_log /var/log/nginx/stats.chalec.org-access.log;
    error_log /var/log/nginx/stats.chalec.org-error.log;

    #return 302 https://$host$request_uri;
    return 302 https://stats.chalec.org$request_uri;
}

server
{
    set_real_ip_from  192.168.0.1;
    real_ip_header proxy_protocol;
    listen 0.0.0.0:444 ssl proxy_protocol;
    listen [::]:443 ssl;

    server_name stats.chalec.org;

    access_log /var/log/nginx/stats.chalec.org-access.log;
    error_log /var/log/nginx/stats.chalec.org-error.log;

    ssl_certificate /etc/letsencrypt/live/stats.chalec.org/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/stats.chalec.org/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

    # StatoolInfos.
    include /etc/nginx/statoolinfos.conf;

    root /var/www/stats.chalec.org;
    location = /
    {
            index index.xhtml;
    }
}
``` 

Vérifier que c'est bon et recharger :
```
nginx -t && systemctl reload nginx
```

# Déploiement du générateur de site web

## Configuration /etc/hosts

Le programme StatoolInfos va faire des requêtes web sur la vm donc il a besoin de la voir.
Pour éviter d'avoir un court-circuit proxy ipv4, modifier le fichier `/etc/hosts` pour déclarer stats.chalec.org en ipv6 locale uniquement :
```
127.0.0.1       localhost
127.0.1.1       stats

# The following lines are desirable for IPv6 capable hosts
::1     localhost ip6-localhost ip6-loopback stats.chalec.org stats
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
```

## Configuration de Java
Java :
```
apt-get install openjdk-11-jre-headless
```

## Espace de travail
Dossiers de travail :
```
mkdir -p /srv/statoolinfos/{bin, cache, conf,inputs,well-known}
mkdir -p /srv/statoolinfos/well-known/statoolinfos/
ln -s /var/www/stats.chalec.org /srv/statoolinfos/www
```

Déployer les catégories : copier le dossier https://framagit.org/chatons/chatonsinfos/-/tree/master/StatoolInfos/categories dans `/srv/statoolinfos/inputs/`.

Créer un fichier de configuration `/srv/statoolinfos/conf/chalec.conf` pour le générateur :
```
# [Configuration]
conf.class=federation
conf.protocol=StatoolInfos-0.5

conf.crawl.input=https://stats.chalec.org/.well-known/statoolinfos/chalec.properties
conf.crawl.cache=/srv/statoolinfos/cache/

conf.htmlize.categories=/srv/statoolinfos/inputs/categories/categories.properties
conf.htmlize.input=https://stats.chalec.org/.well-known/statoolinfos/chalec.properties
conf.htmlize.directory=/srv/statoolinfos/www/
```

Créer le fichier `properties` de type `federation` nommé `/srv/statoolinfos/well-known/statoolinfos/chalec.properties` :
```
# [File]
file.class=federation
file.generator=Cpm
file.datetime=2022-01-12T02:24:35
file.protocol=StatoolInfos-0.4.0

# [Federation]
federation.name=Chalec
federation.description=Le chaton de Libre-en-communs
federation.website=https://www.chalec.org/
federation.logo=https://stats.chalec.org/.well-known/statoolinfos/chalec-logo.svg
federation.contact.url=
federation.contact.email=contact@chalec.org
federation.socialnetworks.mastodon=
federation.legal.url=
federation.guide.user=
federation.guide.technical=
federation.startdate=12/2021
federation.enddate=

# [Subs]
subs.infra=https://stats.chalec.org/.well-known/statoolinfos/infra.properties
subs.services=https://stats.chalec.org/.well-known/statoolinfos/services.properties


# [Metrics]
metrics.members.count.2021 = 2
metrics.members.in.2021 = 2
metrics.members.out.2021 = 0

metrics.members.count.2022 = 2
metrics.members.in.2022 = 0
metrics.members.out.2022 = 0
```

Vérifier la validité des valeurs et placer dans `/srv/statoolinfos/well-known/statoolinfos/` les images de logos nécessaires.

Créer le fichier `properties` de type `organization` nommé `/srv/statoolinfos/well-known/statoolinfos/infra.properties` :
```
# [File]
file.class=organization
file.generator=Cpm
file.datetime=2022-01-12T02:22:02.096451
file.protocol=StatoolInfos-0.5

# [Organization]
organization.name=Infra
organization.description=Les services d'infrastructure de Chalec
organization.website=https://www.chalec.org/
organization.logo=https://stats.chalec.org/.well-known/statoolinfos/chalec-infra-logo.svg
organization.status.level=ACTIVE
organization.status.description=En activité
organization.owner.name=Chalec
organization.owner.website=https://www.chalec.org/
organization.owner.logo=https://stats.chalec.org/.well-known/statoolinfos/alec-logo-carre.png
organization.contact.url=
organization.contact.email=contact@chalec.org
organization.socialnetworks.mastodon=
organization.legal.url=
organization.guide.user=
organization.guide.technical=
organization.startdate=12/2021
organization.enddate=
organization.memberof.chalec.status.level=IDLE
organization.memberof.chalec.status.description=
organization.memberof.chalec.startdate=01/10/2021
organization.memberof.chalec.enddate=
organization.country.name=France
organization.country.code=FR

# [Subs]
subs.stats.chalec.org=https://stats.chalec.org/.well-known/statoolinfos/stats.chalec.org.properties
subs.www.chalec.org=https://www.chalec.org/.well-known/statoolinfos/www.chalec.org.properties
```
Vérifier la validité des valeurs et placer dans `/srv/statoolinfos/well-known/statoolinfos/` les images de logos nécessaires.

Créer le fichier `properties` de type `organization` nommé `/srv/statoolinfos/well-known/statoolinfos/services.properties` :
```
# [File]
file.class=organization
file.generator=Cpm
file.datetime=2022-01-12T02:22:02.096451
file.protocol=StatoolInfos-0.5

# [Organization]
organization.name=Services au public
organization.description=Les services au public de Chalec
organization.website=https://www.chalec.org/
organization.logo=https://stats.chalec.org/.well-known/statoolinfos/chalec-services-logo.svg
organization.status.level=ACTIVE
organization.status.description=En activité
organization.owner.name=Chalec
organization.owner.website=https://www.chalec.org/
organization.owner.logo=https://www.chalec.org/.well-known/statoolinfos/chalec-logo-carre.png
organization.contact.url=
organization.contact.email=contact@chalec.org
organization.socialnetworks.mastodon=
organization.legal.url=
organization.guide.user=
organization.guide.technical=
organization.startdate=12/2021
organization.enddate=
organization.memberof.chalec.status.level=IDLE
organization.memberof.chalec.status.description=
organization.memberof.chalec.startdate=12/2021
organization.memberof.chalec.enddate=
organization.country.name=France
organization.country.code=FR

# [Subs]
subs.audio=https://audio.chalec.org/.well-known/statoolinfos/audio.chalec.org.properties
subs.libreverse=https://libreverse.chalec.org/.well-known/statoolinfos/libreverse.chalec.org.properties
```

Vérifier la validité des valeurs et placer dans `/srv/statoolinfos/well-known/statoolinfos/` les images de logos nécessaires.

Récupérer la dernière version de StatoolInfos sur https://forge.devinsy.fr/devinsy/statoolinfos/releases. Puis placer dans `/srv/statoolinfos/bin/` les fichiers `statoolinfos.jar` et `statoolinfos.sh`. Faire un lien :
```
cd /srv/statoolinfos/bin/
ln -s statoolinfos.sh statoolinfos
```

Dans le fichier `/srv/statoolinfos/bin/statoolinfo.sh`, forcer l'utilsation d'IPv6 :
```
-    java -Djava.awt.headless=true $LOGFILE $LOGLEVEL -jar  "$(dirname "$0")"/statoolinfos.jar $@
 +   java -Djava.net.preferIPv4Stack=false -Djava.net.preferIPv6Addresses=true -Djava.awt.headless=true $LOGFILE $LOGLEVEL -jar  "$(dirname "$0")"/statoolinfos.jar $@
```

-Djava.net.preferIPv4Stack=false -Djava.net.preferIPv6Addresses=true


Créer le script `/srv/statoolinfos/bin/crawl` :
```
#!/bin/bash

cd $(dirname "$0")
./statoolinfos crawl ../conf/chalec.conf
```

Créer le script `/srv/statoolinfos/bin/htmlize` :
```
#!/bin/bash

cd $(dirname "$0")
./statoolinfos htmlize ../conf/chalec.conf
chmod -R go+rX ../www/
```

Créer le script `/srv/statoolinfos/bin/probe` :
```
#!/bin/bash

cd $(dirname "$0")
./statoolinfos probe -previousday ../conf/
```

Créer le script `/srv/statoolinfos/bin/refresh` :
```
#!/bin/bash

cd $(dirname "$0")
./probe
./crawl
./uptime
./htmlize
```

Créer le script `/srv/statoolinfos/bin/uptime` :
```
#!/bin/bash

cd $(dirname "$0")
./statoolinfos uptime ../conf/chalec.conf
```

Donner le droit d'exécution des scripts :
```
chmod u+x crawl htmlize probe refresh uptime
```

Créer le cron `/etc/cron.d/statoolinfos` :
```
4 * * * * root /srv/statoolinfos/bin/refresh >> /srv/statoolinfos/statoolinfos-cron.log
```

# Ajout d'un nouveau service

Tout se passe sur la vm du service, sauf la dernière étape.

## Configuration d'Apache

Création d'un fichier générique `cat /etc/apache2/statoolinfos.conf` qui sera includé plus tard :
```
    Alias "/.well-known/statoolinfos/" "/srv/statoolinfos/well-known/statoolinfos/"
    <Directory "/srv/statoolinfos/well-known/statoolinfos/">
        # Autoriser l'indexation par Apache et donc un affichage même sans index.html ou .php…
        Options +Indexes
        # Forcer le type de fichier correspondant aux extensions .properties avec le support de l'UTF-8.
        # Permet l'affichage dans le navigateur et l'affichage correct des accents par exemple.
        AddType "text/plain; charset=UTF-8" .properties
        # Donner le droit d'accès à tout le monde.
        Require all granted
    </Directory>
```

## Configuration de Nginx
Création d'un fichier générique `cat /etc/nginx/statoolinfos.conf` qui sera includé plus tard :
```
   # location ^~ /.well-known/statoolinfos/  # En cas de conflit de location.
   location /.well-known/statoolinfos/ 
   {
       charset utf-8;
       types 
       {
            text/plain    properties;
       }

       alias /srv/statoolinfos/well-known/statoolinfos/;
       autoindex on;
   }
```

## Espace de travail
Dossiers de travail :
```
mkdir -p /srv/statoolinfos/{conf,well-known}
mkdir -p /srv/statoolinfos/well-known/statoolinfos/
```

## Déclaration du service
Configurer l'accès well-known en ajoutant à la fin de la configuration Apache du site :
```
    # StatoolInfos
    Include statoolinfos.conf
</VirtualHost>
```
Ou au début du bloc `server` du fichier de configuration Nginx du site :
```
    # StatoolInfos.
    include /etc/nginx/statoolinfos.conf;
```

Avertissement : parfois, pour certaines applications, un conflit de `location` peut exister et alors une adaptation est à faire.

Créer le fichier properties de type service à `/srv/statoolinfos/well-known/statoolinfos/foo.chalec.org.properties`. Une documentation des propriétés est disponible là : https://framagit.org/chatons/chatonsinfos/-/blob/master/MODELES/service.properties

Vérifier les permissions de lecture :
```
chmod go+r /srv/statoolinfos/well-known/statoolinfos/*
```

## Renseigner le fichier properties d'organisation

Sur la vm `stats.chalec.org`, éditer `/srv/statoolinfos/well-known/statoolinfos/services.properties` et ajouter une ligne `subs` :
```
subs.foo=https://foo.chalec.org/.well-known/statoolinfos/foo.chalec.org.properties
```

# Génération de métrics

## Configuration de Java
Java :
```
apt-get install openjdk-11-jre-headless
```

## Déploiement de statoolinfos

Récupérer la dernière version de StatoolInfos sur https://forge.devinsy.fr/devinsy/statoolinfos/releases. Puis placer dans `/srv/statoolinfos/bin/` les fichiers `statoolinfos.jar` et `statoolinfos.sh`. Faire un lien :
```
cd /srv/statoolinfos/bin/
ln -s statoolinfos.sh statoolinfos
```

## Configuration
Créer un fichier de configuration dans `/srv/statoolinfos/conf/foo.chalec.org.conf` :
```
conf.class=service
conf.protocol=StatoolInfos-0.5

conf.probe.types=HttpAccessLog, HttpErrorLog
conf.probe.httpaccesslog.file=/var/log/nginx/foo.chalec.org-access.log*
conf.probe.httperrorlog.file=/var/log/nginx/foo.chalec.org-error.log*
conf.probe.target=/srv/statoolinfos/well-known/statoolinfos/foo.chalec.org-metrics.properties
```

Pour prendre connaissance de paramètres de configuration spécifiques, consulter le [projet StatoolInfos](https://forge.devinsy.fr/devinsy/statoolinfos#generate-metrics-files).

Vérifier les permissions de lecture :
```
chmod go+r /srv/statoolinfos/well-known/statoolinfos/*
```

## Génération

Faire une première génération de métrics :
```
/srv/statoolinfos/bin/statoolinfos probe -full /srv/statoolinfos/conf/
```

Vérifier les permissions de lecture :
```
chmod go+r /srv/statoolinfos/well-known/statoolinfos/*
```

Créer un cron `/etc/cron.d/statoolinfos` :
```
2 * * * * root /srv/statoolinfos/bin/statoolinfos probe -previousday /srv/statoolinfos/conf/ >> /srv/statoolinfos/statoolinfos-cron.log
```

Faire un lien :
```
cd /srv/statoolinfos
ln -s /etc/cron.d/statoolinfos cron
```

## Renseigner le fichier properties de service

Sur la vm du service, éditer `/srv/statoolinfos/well-known/statoolinfos/foo.chalec.org.properties` et ajouter une ligne `subs` :
```
subs.foo=https://foo.chalec.org/.well-known/statoolinfos/foo.chalec.org-metrics.properties
```