distorsion.interhacker.space/README.md

Le site web de la distorsion !

TODO

• Héberger nos propre runners ?

Site actuel

Le site est super basique : c'est juste des fichiers statiques html, css et js servis depuis un bucket S3, hébergé chez les camarades de deuxfleurs.

On choisit volontairement de s'imposer des contraintes techniques assez fortes pour que le site reste le plus simple possible, et puisse servir de support pour comprendre les technologies à la base du Web, et on essaye de veiller collectivement à cette simplicité.

Edition

Pour les éditions du site, on a le fonctionnement suivant :

• Pour les petites éditions de contenu, typiquement mettre à jour la liste des évènement à venir : on édite directement (on push dans la branche main).
• Pour ajouter des styles dans le menu de changement de styles, on les ajoute directement aussi.
• Pour tout le reste à priori, comme éditer la structure du site (header, footer, CSS) ou ajouter des billets de blog, on demande aux autres leur avis, sur les canaux de communication ou en vrai, et si ça va à tout le monde on édite. Si on sait utiliser git, on peut faire les modifications dans une branche séparée, et ouvrir une pull request.

Il ne faut surtout pas hésiter à demander de l'aide si ça te semble trop compliqué d'éditer le site !

C'est possible de faire les éditions directes dans l'interface web. Par example, pour rajouter un évènement, on peut : aller dans site, cliquer sur index.html (la page principale du site), cliquer sur le crayon dans la barre au dessus du contenu du fichier pour éditer, et rajouter un pragraphe pour l'évènement. Actuellement, ce serait à la ligne 31 du fichier, et on pourrait ajouter :

<p><strong>Date, heure de l'évènement</strong> et description de l'évènement !</p>

Et enfin, en bas de la page, ajouter une petite description du changement et cliquer sur "Réviser" / "Commit".

Pour ajouter un style, on peut ajouter le fichier css dans le dossier site/css, puis modifier le fichier styleswitcher.js dans site/js pour ajouter son style dans le dictionnaire en haut du fichier, en ajoutant une ligne :

"Nom du style": "/css/fichier-css.css",

Pour les articles de blog, on peut créer un nouveau fichier, y copier-coller le contenu d'un des articles du dossier site/blog, supprimer tout ce qu'il y a entre

et , et rajouter notre contenu à la place. Après, on demande aux autres ce qu'iels pensent de l'article, et si on décide de le publier, on peut ajouter le nouveau fichier dans le dossier blog, puis modifer le fichier blog.html pour y ajouter le nouvel article.

Pour apprendre à faire des sites web, le site MDN de mozilla est une bonne ressource.

Tester le site en local

Pour tester le site en local, il faut un serveur web local. L'une des options les plus simples qui ne demande pas de configuration est d'utiliser celui qui vient avec Python. Dans un terminal, depuis la racine du site, lançer

python -m http.server

Puis pointer un navigateur web vers http://localhost:8000.

Comme on utilise des chemins absolus pour les références entre les fichiers du site, simplement ouvrir les fichiers html avec le navigateur va casser des références (aux fichiers css par exemple, ou des liens). On a besoin de passer par un serveur web pour que le site ait une racine bien définie.

Déploiement

Automatique

Si c'est un bon jour, toutes les modifications dans la branche main sont automatiquement poussées dans le bucket S3 par Woodpecker.

Il faut une clef secrète pour pouvoir accéder au bucket. Avec Woodpecker, on a configuré un "secret" qui contient cette clef, donc pas besoin de la connaître pour mettre à jour le site.

A la main

Si Woodpecker marche pas pour une raison où une autre, on peut copier les sources à jour à la main dans le bucket S3. Pour ça, il faut connaître la clef d'accès au bucket, et son identifiant. Si besoin, on peut les partager.

Il existe plein de clients S3. Avec s5cmd par exemple, ça donne ça :

export AWS_ACCESS_KEY_ID=<key ID>
export AWS_SECRET_ACCESS_KEY=<secret key>
export AWS_DEFAULT_REGION='garage'
export AWS_ENDPOINT='https://garage.deuxfleurs.fr'
s5cmd --endpoint-url $AWS_ENDPOINT sync --delete site/ s3://distorsion.interhacker.space/

La clef et son ID ne sont pas stockées ici. Si besoin, ces secrets peuvent être partagés.

Choix techniques

On essaye de documenter ici les choix techniques qui ont fait l'objet de débats, et qui sont peut être pas évidents.

2024/10/25: Gestion du contenu qui se répète

Les contenus qui se répète sont principalement les éléments <head>, <header> et <footer> qui se retrouvent sur toutes les pages HTML. On a considéré les possibilités suivantes :

• Utiliser un générateur de site simple.
• Utiliser du Server Side Include (SSI) pour charger le serveur web d'ajouter le contenu qui se répète.
• Ecrire un petit script bash qui ajoute le contenu commun avec des simples cat et sed.
• Ecrire un petit script JavaScript qui ajoute le contenu commun dynamiquement à toutes les pages.

Ces solutions ont toutes le désavantage de rendre le site plus "opaque". Les fichiers que l'on voit dans le dépot ne sont plus directement ceux qui sont servis au navigateur, ce qui ajoute une barrière supplémentaire à une personne qui essaye de comprendre le site. Les deux dernières sont une pente glissante vers la réécriture d'un générateur de site maison (ce qui n'est pas forcément mal). Le SSI n'est pas vraiment une option tant que le site est hébergé chez DeuxFleurs, car leur infrastructure ne le supporte pas.

On a donc décidé de répéter le contenu dans tous les fichiers. Si on écrit bien les parties redondantes, elles ne devraient pas être modifiées très souvent. Quand c'est le cas, on peut facilement comprendre la tâche à faire, et éventuellement écrire un petit script bash simple pour réaliser cette tâche. C'est l'occasion d'apprendre quelque chose ensemble.

Evidemment, c'est pas idéal comme situation. Y'a un risque que les parties qui sont censées être communes finissent par se désynchroniser. On verra bien à l'usage.

2024/10/25: Flex

Pour centrer le contenu sur toutes les pages dans le css par défaut, on a décidé de transformer le <body> en un conteneur flex. Flex c'est un peu compliqué (nous même on comprend pas bien comment ça marche) mais ça permet que tous les nouveaux éléments ajoutés dans la page comme enfant du <body> soient centrés, sans qu'il ne faille ajouter margin: auto dessus à chaque fois.

Ancien site

Avant, on avait un site static généré avec Hugo. Les sources sont archivées dans l'historique de git.