HOWTO être respo web¶
Si vous vous êtes retrouvé ici, c'est probablement que vous êtes respo web pour un club ou une association (ou peut-être même une liste ?👀👀).
Vous trouverez sur cette page tout ce qu'il faut savoir pour :
- Demander l'ajout d'un site
- Demander un accès pour mettre à jour un site
- Mettre à jour un site.
- Gérer la connexion au CAS
Imposante la brasse 😱
Cette page de documentation est assez longue, n'hésitez pas à utiliser le sommaire à droite pour aller directement à la section qui vous intéresse.
Comment demander l'ajout d'un site¶
Pour demander l'ajout d'un site, il suffit de demander gentiment à un membre du bureau d'Eirbware !
Voici différentes manières d'en contacter un :
- Le contacter directement sur Telegram si vous en connaissez un
- Envoyer un message sur le groupe Discussion d'Eirbware sur Telegram
- Envoyer un mail à eirbware@enseirb-matmeca.fr
Comment demander un accès pour mettre à jour un site¶
La modification d'un site web se fait par SFTP, qui est un protocole construit à partir de SSH. Et l'accès se fait exclusivement par clef.
Les instructions suivantes permettent de savoir comment créer une clef SSH et la configuration pour mettre à jour un site.
Création d'une clef SSH¶
Il est conseillé de créer une clef SSH spécifiquement pour Eirbware, vous pouvez en créer une de la façon suivante :
Après l'exécution de cette commande, deux fichiers ont été créés : une clef privée filename et une clef publique filename.pub.
Sécurité des clefs
Vous ne devez pas, sous aucun prétexte, partager la clef privée, cela permettrait à un tiers d'usurper votre identité.
Cependant, vous pouvez partager la clef publique, elle ne sert à rien sans la clef privée.
Certificat SSH¶
Eirbware utilise des certificats SSH afin d'autoriser la connexion d'une paire de clefs SSH au serveur. Pour en créer un, Eirbware a besoin de la clef publique que vous venez de générer pour créer un certificat.
Vous devez donc à partir de là contacter un membre d'Eirbware comme proposé en haut de cette page pour demander de vous créer un certificat.
Durée de validité des certificats
Par défaut, les certificats sont valides 1 an, vous devrez peut-être demander un renouvellement de votre certificat.
Configuration SSH¶
Finalement, vous pouvez créer une configuration SSH, vous devez rajouter dans votre fichier ~/.ssh/config les lignes suivantes (exemple pour pixeirb, vous devez les adapter au site que vous maintenez) :
| ~/.ssh/config | |
|---|---|
Avec ceci, vous avez tout pour passer à l'étape d'après : Comment mettre à jour un site ?
Comment mettre à jour un site¶
Pour ce faire, vous aurez besoin d'un client SFTP, la commande sftp fonctionne très bien sous linux, et un montage sshfs peut vous plaire.
Cependant, il est compréhensible que des interfaces graphiques soient plus agréables, la plupart des gestionnaires de fichiers vous permettront de vous connecter en SFTP de la manière suivant.
Gestionnaires de fichiers testés
La plupart des gestionnaires de fichiers doivent fonctionner, mais nous n'avons testé que nemo, nautilus et thunar
Connexion en SFTP¶
Si vous avez bien configuré votre fichier ~/.ssh/config comme précédemment, vous pouvez maintenant vous connecter au serveur d'EIRBWARE en SFTP, nous préconisons 3 méthodes :
- Avec la commande
sftp - Monter avec
sshfs - Utiliser un gestionnaire de fichiers
Avec la commande sftp¶
En utilisant la commande sftp, vous n'avez qu'à faire :
Vous êtes maintenant connecté en SFTP à Eirbware avec un client CLI.
Monter avec sshfs¶
En utilisant la commande sshfs, vous pouvez monter le dossier du site web via SFTP vers un dossier local, ici ~/mnt.
Droits d'accès aux fichiers
Pour pouvoir monter dans le dossier ~/mnt, vous devez en être propriétaire.
Droits d'accès à la configuration ssh
Si vous exécuté la commande en root avec sudo, le fichier /root/.ssh/config sera utilisé pour la configuration ssh, pas le votre
Utilisation de -f
Nous conseillons d'utiliser le flag -f de sshfs, il permet, il permet de ne pas avoir à démonter le dossier après coup, et de savoir clairement quand on est connecter ou non.
Utilisation des options -o
En utilisant le flag -oauto_cache,reconnect,no_readahead, il est possible de gagner énormément en vitesse de transfert (~10x). Il est donc conseillé de l'utiliser.
sshfs -f eirb_pix: ~/mnt -oauto_cache,reconnect,no_readahead
Vous avez maintenant accès aux fichiers du site web en passant par le dossier ~/mnt.
Monter avec votre gestionnaire de fichier¶
Écrivez dans la barre de recherche de votre gestionnaire de fichier (Contrôle-L) :
Vous avez maintenant accès aux fichiers du site web directement depuis votre gestionnaire de fichier.
Mettre à jour les fichiers¶
En fonction du type de site web, la mise à jour se fait différemment.
Site statique ou php¶
Eirbware utilise docker pour tous les sites hébergés. Pour des raisons techniques, la plupart des sites sont de cette forme :
/docker-compose.yml # Définis Docker nginx, pas besoin de modifier
/nginx # Dossier partagé avec le docker
/nginx/nginx # Configuration nginx
/nginx/php # Librairies php
/nginx/www # Code du site
/nginx/log # Log de nginx
/nginx/keys # Inutilisé
Pour plus de détails sur le docker utilisé, vous trouverez la documentation ici.
Si vous voulez mettre à jour le site, il suffit donc de modifier le contenu du dossier /nginx/www.
Site conteneurisé¶
Si le site que vous maintenez utilise un backend autre que php, vous allez probablement utiliser un fichier docker-compose.yml fait sur-mesure.
Si tel est le cas, nous n'avons probablement aucune documentation sur ce dernier, il est de la responsabilité du club ou de l'association de mettre en œuvre les outils nécessaires à la maintenabilité du site web.
Voici tout de même des informations à connaître pour savoir comment gérer un tel site :
- Vous pouvez upload un Dockerfile pour compiler sur le serveur
- Évitez d'upload le dossier
.git - Pour redémarrer ou recompiler le docker, faites le sur portainer.vpn.eirb.fr
Portainer
Pour plus d'information sur l'accès au portainer, référez-vous à la section VPN plus bas.
Ports exposés
Nous n'autorisons qu'un forward de port de localhost à un conteneur. Ce port est précisé dans le fichier /README.md de votre site, si vous avez besoin d'exposer plusieurs conteneurs, utilisez un reverse proxy
Caddy peut être une solution adaptée pour mettre en place facilement un reverse proxy avec un Caddyfile.
Accès au VPN¶
Certains outils d'administration sont installés sur le serveur, pour des raisons de sécurité, ces outils ne sont pas accessibles par internet.
Parmi ces outils, seul Portainer vous concerne.
Accès à *.vpn.eirb.fr
L'accès à ces noms de domaines se fait uniquement via le VPN, et vous devrez utiliser le DNS qui est sur ce VPN, vérifiez que le DoH n'est pas activé sur votre navigateur.
Demander un accès¶
De la même façon que pour l'accès SFTP, il vous faut contacter un membre d'Eirbware, voici quelques techniques :
- Le contacter directement sur Telegram si vous en connaissez un
- Envoyer un message sur le groupe Discussion d'Eirbware sur Telegram
- Envoyer un mail à eirbware@enseirb-matmeca.fr
On vous transmettra à l'issue de cette demande un fichier wg_eirb.conf qui est un fichier de configuration pour wireguard.
Installer un logiciel pour se connecter¶
Il vous faudra télécharger un client pour wireguard.
Se connecter sous linux¶
Normalement, vous avez téléchargé un client wireguard en utilisant le gestionnaire de paquets de votre distribution.
Le paquet que vous avez installé vous a normalement installé le script wg-quick, vous pourrez vous connecter au VPN en utilisant la commande suivante dans un shell :
Chemin vers la config wireguard
Vous devez spécifier un chemin relatif ou absolu vers la configuration wireguard, comme ./wg_eirb.conf ou /tmp/wg_eirb.conf, sinon wg-quick essayera de trouver le fichier dans /etc/wireguard.
Pour vous déconnecter, exécutez :
Se connecter sous Windows¶
jsp comment faire mdr
Gérer la connexion CAS¶
Le CAS a toujours été un problème très ennuyeux à gérer.
Nous avons essayé de trouver deux solutions pour que la mise en place d'une connexion CAS soit la plus simple possible.
En utilisant notre API "protect"¶
Si votre site est statique ou est fait en PHP, et utilise la configuration nginx par défaut, nous vous conseillons cette solution.
Il s'agit d'un petit serveur PHP présent dans toutes les configurations par défaut, nous proposons une librairie javascript pour l'utiliser depuis le site web.
Pour télécharger la librairie, et avoir plus de documentation au sujet de protect, allez sur ce dépôt.
En utilisant OpenID avec keycloak (connect.eirb.fr)¶
Étant donné que le CAS est assez désagréable à utiliser, et n'est pas accessible en local, nous avons mis en place un relais d'authentification avec keycloak.
Vous pourrez utiliser ce système d'authentification à l'aide de librairies (OpenID Provider), OpenID en liste un certain nombre
Voici une liste plus timide que vous pouvez utiliser :
- PHP : OpenID-Connect-PHP
- JS/TS : openid-client
Pour pouvoir vous utiliser OpenID, vous devrez utiliser un secret, vous le trouverez avec une configuration dans le dossier du site web que vous maintenez.
Conseil de la part d'Eirbware¶
Il existe aujourd'hui beaucoup de technologies pour créer des sites web, et il y a de quoi se demander "Quelle technologie devrais-je utiliser ?".
Voici quelques conseils que nous avons à vous partager en prenant en compte le système associatif de l'ENSEIRB.
Contrainte principale de l'associatif
Les clubs et les associations de l'ENSEIRB changent de membres tous les ans, il est primordiale de s'assurer que le mandat suivant puisse maintenir le site.
Considérez le vanilla¶
Considérez de faire votre site en HTML/CSS/JS vanilla, voici les avantages :
- S'il y a un respo web dans le prochain mandat, il maitrisera les technologies
- Pas besoin d'avoir un dépôt git pour stocker les sources
Cependant, écrire un code scalable en vanilla n'est pas trivial, notamment pour l'écriture du CSS. Il est conseillé d'utiliser la convention BEM pour s'en sortir en écrivant ce genre de site.
Si le vanilla vous fait peur¶
L'avantage du vanilla est qu'il est censé être un prérequis aux autres technologies web, ce qui le rend universel. Le maintenir peut tout de même être pénible.
Voici des notes à propos des alternatives.
La contrepartie très importante
Un site qui n'est pas fait en vanilla, nécessite d'être compilé !
La version sur eirb.fr ne peut donc pas suffire à une passation, un dépôt git et des instructions de compilations doivent être transmise au prochain mandat pour que le site soit maintenable.
Conseil pour gérer un dépôt git
Considérez la création d'une organisation github, cela permet de simplifier une passation : il n'y a plus qu'à changer le propriétaire de l'organisation
Le cas Typescript¶
Le manque de typage en javascript est clairement ennuyeux, et l'utilisation de typescript est clairement intéressant.
Les frameworks CSS¶
Les frameworks comme tailwindCSS et bootstrap se comprend : cela permet de gérer le responsive plus facilement, et d'accélérer la phase de développement.
Voici une liste assez imposante de frameworks.
Les frameworks JS¶
En derniers viennent les frameworks JS, faire un site en React est tentant, mais on a toujours la même problématique : tout le monde ne connait pas React.
Générateurs de sites statiques¶
En fonction du besoin, les générateurs de sites statiques (comme Material for mkdocs utilisé pour le site sur lequel vous êtes) peut être une très bonne solution.
Ils permettent de générer un site web en vous concentrant sur le contenu.
Technologies pour un backend¶
Si vous avez absolument besoin d'un backend, vous pouvez utiliser la technologie que vous voulez, car tous les sites sont conteneurisés.
Cependant, comme dit précédemment, potentiellement personne ne pourra maintenir le site dans le futur.
Considérez notre API protect d'abord
L'API que nous proposons avec protect permet quelques fonctionnalités avec une connexion CAS, peut-être que c'est suffisant pour vos besoins.
Peut-être que votre besoin peut être rajouté à protect, si votre besoin est proche de ce que cette API propose, considérez d'en parler à Eirbware pour que ça soit rajouté.
Si vous avez besoin d'un backend, nous vous conseillons :
- De garder le backend le plus simple possible
- Pour une base de donnée, restez sur postgres ou sqlite
- Restez sur du SQL, c'est étudié en cours, pas mongodb, ni redis
- D'utiliser git pour versionner le code, et le transmettre aux passations
Pour ce qui est des technologies pour un backend, nous vous conseillons :