distorsion.interhacker.space/README.md

[![status-badge](https://woodpecker.deuxfleurs.fr/api/badges/41/status.svg)](https://woodpecker.deuxfleurs.fr/repos/41)

# 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](https://deuxfleurs.fr).

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 <main> et </main>, 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](https://developer.mozilla.org/fr/docs/Learn) 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](https://gohugo.io). Les
sources sont archivées dans l'historique de git.