Jujens’ blog - Blog

Jouer sous Linux

2025-12-20T00:00:00+01:00

Après plusieurs tests infructueux l’année dernière, j’ai décidé de retester le jeu sous Linux en avril 2025 avec une nouvelle config. Et je dois admettre que ça fonctionne vraiment très bien. Je n’ai presque pas de problèmes et un seul jeu aurait nécessité de repasser sous Windows le temps qu’un correctif le corrige. Il y a toutefois quelques points sur lesquels j’ai un peu coincé et qui méritent qu’on les détaille. Ce que je vais faire dans cet article.

J’ai essayé de faire des sections claires pour vous permettre de ne lire que ce qui vous intéresse.

TL;DR : ça fonctionne très bien et je ne joue plus du tout sous Windows. On peut quand même avoir des petits soucis qui finissent par être corrigés. Si vous voulez être sûr de pouvoir jouer à n’importe quel jeu dès sa sortie, mieux vaut garder un Windows dans un coin au cas où.

Contents

Contexte
Vers le jeu sous Linux
- Avec Steam
- Et GoG ?
Les jeux

Contexte

Tout d’abord, un peu de contexte. J’ai essayé l’année dernière vers décembre après que des collègues m’aient dit jouer sous Linux sans problème. Malheureusement, sur mon ancienne config avec une vieille Nvidia GTX 1070, je n’ai jamais réussi à lancer les jeux Steam à cause d’une erreur sur la carte graphique. Mes recherches n’ont rien donné et après plusieurs tests, j’ai lâché l’affaire et je suis retourné sous Windows.

Je suppose que le souci n’était pas matériel ni au niveau de l’OS car mes jeux GOG fonctionnaient sans souci apparent (je n’ai pas poussé mes tests très loin).

En début d’année 2025, comme plusieurs jeux qui m’intéressaient allaient sortir et que ma machine commençait à vieillir, j’ai décidé de refaire ma config. C’est surtout la carte graphique qui posait problème : j’avais acheté un écran 1440p fin d’année dernière et la GTX 1070 montrait ses limites sur les jeux récents. En 1080p, je trouve qu’elle fonctionne toujours très bien et les jeux, même récents, restaient beaux. Au delà des problèmes de performances, les mises à jour du noyau avaient tendance à rater sous openSUSE Tumbleweed (ma distro) car les pilotes ne sont pas mis à jour rapidement dans le dépôt Nvidia.

J’ai décidé de partir sur une carte AMD RX9070XT, en grande partie à cause de ces soucis de support des cartes Nvidia sous Linux. De ce que j’ai compris, sur les modèles plus récents, le pilote officiel est mieux intégré au noyau et on évite toutes ces galères. Je pense quand même qu’AMD est un meilleur choix, ne serait-ce que pour leur meilleur support de Linux depuis de nombreuses années. Tout test simple : rien à installer, tout vient de base avec le noyau.

Je signale quand même un souci que j’ai eu avec la carte : le son pouvait produire des genres de craquements via Display Port à la lecture de musique (je n’ai jamais eu de souci en jeu bizarrement). Une mise à jour de noyau vers une nouvelle version a résolu le souci. Comme la carte est un modèle récent, je pardonne. Cela reste un point à garder en tête : si vous prenez du matériel récent, mieux vaut une rolling release ou une distro comme Fedora bien à jour.

Une fois la config montée, j’ai commencé par vérifier que tout semblait bon sous Windows en jouant un peu. J’ai vite eu l’impression que le système n’était pas très stable avec plusieurs jeux qui ont planté et bien plus qu’avec ma vieille GTX 1070. Surement, car je n’ai pas réinstallé Windows en changeant de carte. J’ai simplement désinstallé les pilotes Nvidia et installé ceux d’AMD. Je suppose qu’une réinstallation propre de Windows règlerait le souci, mais, comme j’arrive à jouer sous Linux sans souci, eh bien, je ne vais pas me prendre la tête avec ça. Windows va rester installé au cas où, ne serait-ce que pour déboguer mon imprimante.

Vers le jeu sous Linux

Avec Steam

Comme dans mes tests de fin 2024, j’ai eu des soucis avec Steam, quand bien même c’est ce que tous les joueurs sous Linux que je connais me vendaient comme la panacée. J’ai décidé de passer par le Flatpak pour que les jeux n’aient pas accès aux documents système par sécurité. Cela vient peut-être du fait que je me souviens d’un gros bogue de Steam qui supprimait tous les fichiers de $HOME il y a quelques années.

Par défaut, seuls les jeux natifs Linux peuvent être installés et lancés. Pour lancer n’importe quels jeux, il faut activer Steam Play pour tous les jeux dans les paramètres section "Compatibilité". Une fois cela fait, je télécharge un jeu et j’essaie de le lancer.

Et c’est le drame. Rien ne se passe. Même pas un message d’erreur.

J’essaie avec un autre jeu, et même problème. J’essaie différentes versions de Proton (la couche de compatibilité de Valve pour jouer aux jeux Windows sous Linux qu’on peut configurer en cas de souci). Sans succès.

Je me suis dit qu’il me manquait peut-être certains paquets. J’ai essayé d’en installer plusieurs en lien avec Mesa ou AMDGPU. Sans succès.

J’ai essayé un jeu GOG via Heroic Game Launcher qui a fonctionné sans problème avec Wine.

Finalement, j’ai essayé d’installer le paquet Steam fourni par les dépôts. Le gestionnaire de paquets a ajouté plusieurs autres paquets et, miracles, je pouvais jouer. J’ai réessayé la version Flatpak qui fonctionne aussi correctement une fois ces paquets installés. J’ai décidé de rester sur la version Flatpak avec le paquet installé et pour séparer mes activités et être sûr qu’aucun jeu n’aura accès à mes fichiers, j’ai aussi créé un utilisateur dédié pour le jeu. Mais c’est peut-être juste moi qui suis un peu parano.

Après plusieurs mois de jeux sous Linux, je ne me vois plus lancer un Windows. Ça fonctionne trop bien ! Je suis même surpris d’à quel point ça fonctionne bien, y compris sur des jeux comme Avowed, The Outer Worlds 2, Assassin’s Creed Shadows qui sont sortis cette année.

J’ai même réussi à jouer à Mass Effect Legendary Edition et Dragon Age Inquisition qui nécessite cette 🤬 d’EA app. Notez que je passe par Steam pour lancer les jeux : Steam installe et lance l’EA app automatiquement et ça fonctionne aussi bien (ou mal) que sous Windows. Il suffit de se connecter à l’EA app. Malheureusement, après une mise à jour de l’EA app, DA:I ne se lançait plus (idem pour Mass Effect. Supprimer manuellement un fichier de cache a réglé le souci. Pour cela, il faut : trouver l’id Steam du jeu (visible dans les paramètres du jeu dans la section "Mise à jour") puis supprimer le dossier ~/.var/app/com.valvesoftware.Steam/.local/share/Steam/steamapps/compatdata/<APP_ID> (c’est le chemin avec Flatpak, ça devrait être quelque chose comme ~/.local/share/Steam/steamapps/compatdata/<APP_ID> pour la version standard). Ça me confirme dans l’idée que l’EA est naze.

Quelques petits soucis quand même :

Sur Dragon Age the Veilguard, les coiffures de certains personnages se sont mises à scintiller après une mise à jour système. Le jeu restait jouable, mais avait un aspect très bizarre. Une autre mise à jour quelque temps après a réglé le souci.
Avec Indiana Jones and the Great Circle, j’ai dû attendre plusieurs mois avant que le jeu ne se lance correctement. Les textures n’étaient pas rendues correctement et le jeu était injouable. C’est le plus gros souci que j’ai eu et le seul jeu non jouable.

Et GoG ?

En plus de Steam, j’ai aussi une belle bibliothèque sur GoG. Même si elle n’a pas d’app compatible Linux, elle reste ma boutique de choix : les jeux n’ont pas de DRM et elle est basée en Europe. Pour me simplifier la vie, j’ai choisi de passer par Heroic Game Launcher installé via Flatpak (qui gère aussi les jeux Epic Games Store). C’est surtout pour ça que j’aime Flatpak : être sûr d’avoir des logiciels pas très courants correctement packagé pour Linux.

En soi, le fonctionnement est très proche de Steam : on peut installer les jeux et les lancer. L’app se charge de les garder à jour et traque le temps de jeu. Les succès ne sont pas visibles dans l’app, mais sont correctement débloqués (j’ai vérifié sous l’app GoG sous Windows).

Petit point de configuration pour que les jeux natifs Linux se lancent : il faut configurer le lien vers les fichiers de compatibilité de Steam. Sans, certains jeux ne peuvent pas se lancer, car ils nécessitent une vieille version d’openSSL. Pour cela, il faut s’assurer que le paramètre "Chemin par défaut vers Steam" pointe bien vers ~/.var/app/com.valvesoftware.Steam/.local/share/Steam (je suppose que c’est ~/.local/share/Steam pour la version standard). Ça devrait être le cas par défaut.

Les jeux

Pour terminer, voici une liste des jeux auxquels j’ai joué cette année sous Linux avec la date de sortie du jeu, l’application utilisée (Steam ou Heroic) et quelques commentaires. Principalement mon temps de jeu ou si j’ai eu des soucis (et dans ce cas, lesquels).

Dragon Age: the Veilguard, 2024, Steam : presque complet (j’ai démarré sous Windows). Le jeu est plus stable avec les paramètres élevés que sous Windows. Quelques plantages à l’utilisation du pouvoir ultime ou lors de très gros combats. Réduire le ray tracing a résolu le souci. J’ai eu exactement le même problème au même endroit sous Windows avec mon ancienne config.

Le curseur n’est pas le même que sous Windows et semble troué. Étrange, mais pas impactant.

Plus grave, j’ai eu un souci avec le rendu des cheveux après une mise à jour : ils scintillaient. Le jeu restait jouable, mais était très moche. Ça a mis plusieurs semaines à revenir à la normale avec une mise à jour système.
Pillars of Eternity, 2015, Heroic : jeu de base complet, sur mon portable. J’ai utilisé la version Linux avec les compatibilités Steam pour éviter les soucis avec la vieille version d’openSSL dont le jeu a besoin. Ça fonctionne très bien.
Avowed, Steam, 2025 : fonctionne bien en paramètres max, et ce, dès sa sortie. Je n’ai pas eu un seul crash sur la totalité du jeu. Seul petit souci rencontré : des gels graphiques de temps en temps, en général après un changement de zone. Ces gels disparaissent après quelques secondes. C’est plus agaçant qu’autre chose.
Age of Empires IV, 2021, Steam : j’ai joué plusieurs dizaines d’heures en solo et en multi sans souci.
Age of Mythology Retold, 2024, Steam : j’ai joué plusieurs dizaines d’heures en solo et en multi sans souci.
Indiana Jones et le cercle ancien, 2024, Steam : j’ai joué plusieurs heures sans souci après des débuts compliqués. Quand j’ai essayé pour la première fois, les textures étaient complètement cassées. Ça a fini par fonctionner après une mise à jour système. J’ai des lenteurs quand la caméra tourne même en texture moyenne ou avec fsr et textures élevées ou moyennes. C’est le seul jeu avec ce problème et celui qui fonctionne le moins bien. Comme je n’y ai pas accroché, je n’ai pas cherché plus loin.
Mass Effect Legendary, 2021, Steam : jeu complet, aucun souci. Après avoir eu des soucis à cause de l’EA app avec Dragon Age Inquisition (voir le jeu suivant), j’ai essayé de le relancer et j’ai eu le même comportement. La même solution a corrigé le souci.
Dragon Age Inquisition, 2014, Steam : jeu complet, y compris les DLCs. J’ai eu quelques bogues de quêtes qui se valident en boucle. La quête finit par se valider correctement après plusieurs "essais". J’ai aussi eu un plantage avant le boss de fin.

Plus grave : suite à une mise à jour de l’EA app, le jeu ne se lançait plus du tout. J’ai dû vider le cache en supprimant un dossier à la main. Voir le détail dans la section avec Steam.
Baldur’s Gate 3, 2023, Heroic : quelques heures, RAS.
Dragon Age Origins, 2009, Heroic : j’ai seulement fait le prologue, RAS.
Witcher 3, 2015, Heroic : plusieurs heures de jeux, RAS.
The Outer Worlds Spacer Choice edition, 2019, Heroic : jeu complet, RAS.
Pathfinder Wrath of the Righteous, 2021, Heroic : quelques heures, RAS.
Assassin’s creed Odyssey, 2018, Steam : quelques heures, RAS.
Assassin’s creed Shadows, 2025, Steam : jeu de base, joué dès sa sortie, RAS.
Horizon Zero Dawn, 2017, Steam : jeu complet, RAS.
The Outer Worlds 2, 2025, Steam: jeu complet, joué dès sa sortie, RAS.
Horizon forbidden west, 2022, Steam : quelques heures, RAS.
Spellforce 3 versus, 2017, Steam : quelques heures, RAS.

À propos de mon blog

2025-09-05T00:00:00+02:00

Après plus de dix ans, voici mon 200e article de blog ! J’ai décidé que ce serait un bon moment pour faire un point sur ces années et envisager le futur.

J’ai démarré ce blogue en 2013 alors que j’étais encore étudiant à Centrale Marseille. Il était alors fait en Drupal et hébergé sur les serveurs de l’école.

J’ai assez rapidement décidé d’en faire un site statique pour avoir quelque chose de plus simple et de plus facilement hébergeable et de le migrer sur mon domaine pour être plus indépendant (ma remise de diplôme approchait). Comme je faisais déjà pas mal de Python, j’ai choisi Pelican un générateur écrit en Python. De mémoire, j’avais aussi regardé Jekyll une autre solution très populaire à l’époque écrite en Ruby. Aujourd’hui, j’étudierai aussi Hugo une solution écrite en Go qui me semble de plus en plus populaire.

Pour ce blogue, je compte rester sur Pelican : ça fonctionne très bien, c’est suffisant pour mes besoins et comme j’ai peu d’articles le site est généré en moins d’une seconde. Je n’ai donc pas besoin des performances d’Hugo. En somme, aucune bonne raison de changer. Changer serait même difficile : mes articles sont écrits en reStructuredText et pas en Markdown (plus d’info à ce sujet ci-dessous) ce qui fonctionne avec Python moins dans les autres langages.

Le blogue a assez peu changé : je continue à bloguer sur les sujets tech qui m’intéressent. Certaines catégories n’ont pas eu d’articles récemment n’en auront surement jamais : elles correspondent à mes sujets d’intérêts quand j’ai lancé le blog. Seule la programmation est vraiment restée. L’expérience aidant, j’ai aussi l’impression d’avoir moins de sujets qui méritent un article. De ce point de vue, 2025 s’annonce comme une année exceptionnelle avec beaucoup de sujets.

Mon blogue reste assez peu connu. C’est principalement ma faute, je fais peu de pub, car ça ne m’intéresse pas. Il faut croire qu’écrire pour moi-même me suffit et que je préfère clarifier mes idées au fait d’être lu. Au début, je postais les liens sur Twitter pour avoir un peu de visibilité. Désormais, j’ai quitté Twitter où je n’étais de toute façon pas actif. J’ai un compte Mastodon, plus pour suivre des choses que pour poster. Et peu de personnes me suivent.

J’ai toujours des statistiques anonymes et compatibles RGPD sans bannière de cookies. Au début, j’autohébergeais une instance Matomo. Pour me simplifier la vie et gagner du temps, je suis passé sur plausible cette année : c’est simple, suffisant pour mon usage, RGPD compatible par défaut et pas très cher (9 € par mois, ce que je peux me permettre maintenant). Mon article le plus vu d’année en année reste un article publié en 2013 sur la création d’une page de garde en LaTeX avec le double de vues des autres articles. Au coude à coude viennent ensuite un article sur l’utilisation de trap en Bash et sur un sur les espaces de nom dans Docker. Pour les articles publiés cette année, celui sur uv et ruff et celui sur Pydantic et les enums fonctionnent très bien.

La langue d’écriture a aussi changé. Initialement, j’écrivais tout en français, puis j’ai proposé des traductions de mes articles en anglais pour accroitre leur visibilité. Comme la traduction demandait beaucoup de temps, maintenant j’écris en anglais, sauf pour de rares articles spéciaux comme celui-ci.

L’hébergement a changé également. Je suis passé d’un site Drupal, à un site statique hébergé sur mon VPS à un site statique dans des buckets (chez Scaleway pour éviter les géants américains). C’est encore plus simple (plus de serveur), et fonctionne très bien. C’est aussi moins cher. J’ai configuré la CSP via le HTML, car je n’ai pas l’impression qu’on puisse configurer ces entêtes dans les buckets. Je trouve que c’est moins bon, mais ça fonctionne. Je garde un VPS pour d’autres projets qui ont besoin d’un serveur, dont mes commentaires qui restent autohébergés grace à isso.

Concernant le format des sources, je suis toujours sur reStructuredText. Pelican fonctionne avec reSTtructuredText (via docutils l’implémentation de référence pour ce format) et Markdown par défaut. À titre personnel, je n’ai jamais accroché au Markdown : je le trouve pas assez spécifié et il a trop de variantes pas forcément compatibles entre elles. Avec reStrucuturedText, je peux inclure des fichiers, avoir les numéros de lignes à côté du code… J’ai donc plus de fonctionnalités qui fonctionnent correctement et sont correctement standardisées. Cela me convient mieux, même si je dois reconnaitre que le format manque de flexibilité. C’est, je pense, la force de Mardown : les cas simples sont gérés correctement par tout le monde et pas de prise de tête avec l’indentation, on écrit du texte un peu n’importe comment et ça fonctionne. Je doute qu’un langage à balisage sans cette caractéristique puisse devenir populaire, même si parser les cas plus complexes ou avoir toutes les fonctionnalités dont vous avez besoin est plus difficile.

Et l’IA dans tout ça ? Je n’ai pas vraiment d’avis. Comme la visibilité n’a que peu d’impact, je vais continuer à bloguer même si moins de personnes visitent mon blog. Si ça devient vraiment un souci et que je ne veux pas nourrir les LLM, je pense que je continuerais à écrire, pour moi sans rien publier. Ce serait dommage, car je sais que certains de mes articles sont utiles. Affaire à suivre…

Pour finir : je suis très content de ce blogue. Il me force à mettre mes idées au clair, me permet de partager certaines trouvailles, et, je pense, qu’il a fait de moi un meilleur développeur. Je compte continuer à bloguer quand j’ai envie sur les sujets qui m’intéressent. Je ne pense pas changer quoique ce soit sur la partie technique : ça fonctionne et j’en suis satisfait. Le fait que le blogue soit statique est un gros avantage, je pense, et je ne peux que vous recommander de faire un site statique vous aussi, si vous voulez un blogue : tout est plus simple, on peut utiliser git pour gérer les articles et il y a pléthore de bons outils pour vous simplifier la tâche.

Note

Dans un bucket, on ne peut pas définir des entêtes HTTP personnalisés dont X-Frame-Options pour empêcher l’inclusion du site dans une iframe. Utiliser <meta http-equiv="X-Frame-Options" content="DENY"> n’a pas d’effet. De même, la directive frame-src de Content-Security-Policy n’a pas d’effet au sein d’un élément meta (contrairement aux autres directives). Voir X-Frame-Options header et Content-Security-Policy: frame-src directive.

Tant que ces entêtes ne pourront pas être utilisées, j’ai décidé d’utiliser ce code javascript pour afficher une page vide quand le site est inclus dans une iframe (pour les utilisateurs qui ont javascript activé, ce qui devrait être la plupart des utilisateurs de nos jours) :

if (window.parent !== window) {
    window.location.replace('about:blank');
}

From matomo to plausible

2025-03-09T00:00:00+01:00

For several years, I hosted my own Matomo instance to track traffic on my blog and projects while respecting the privacy of my users. It worked well, but it was the only service I had running on MariaDB. All the other ones are running on PostgreSQL. And I had several issues with MariaDB and file corruption over the years, mostly on unexpected server shutdown. Most of the time, I managed to recover the data, but I also lost some if it, sometimes just because MariaDB couldn’t start so Matomo was down for a while. Regarding Matomo itself, it is very feature complete, but is resource intensive (and thus a bit slow on my server). I also always found the interface a bit messy.

Since I’m in the process of cleaning up my servers, I wandered if I could find an alterative. Ideally, I want a free software I can self host. I’d like the data to be in my PostgreSQL instance and the project itself will run in a container (so no barrier regarding runtime language). I had to objection paying a small fee for a good service if needed: I can afford it and it could make my life way easier. Whatever I choose, I wanted something RGPD compatible that respects the privacy of my users.

After some research, I found three possible options:

Matomo which I don’t want to self host any more. Their paid plan starts at 22€/month which I find expensive given my very small usage. On the other side, it’s feature complete, privacy focussed and is well known.
Umami an MIT project written in TypeScript. It supports multiple database including PostgreSQL. It is developed by a US company. It has a free plan that would suit my needs. The next tier starts at $20/month. They don’t rely on cookies to track users but I didn’t find their documentation more details about how they comply with the RGPD or how they respect users privacy. And I failed to find where the data is hosted for their Cloud plan.
Plausible an AGPLv3 project written in Elixir. In the many list of projects, it’s the only one I had heard of before hand. While it supports PostgreSQL, it also requires ClickHouse (a no-sql database designed for analytics). Running the full stack with docker compose worked well, but it’s probably not the easiest one to self-host. Their cheapest plan (which fits my needs) starts at 9€/month which is acceptable for me. It is developed by a European company and their cloud service is hosted in Europe by Hetzner a German hosting provider. Furthermore, their documentation is very clear and complete regarding how they respect the RGPD and users privacy. It’s not the most feature complete, but it has just what I need and is also efficient and simple to use. Their tracking script is also very lightweight.

I started by using the trial the trial period to easily test the tool. I ran it in parallel with my self hosted Matomo to spot any differences. Since they don’t track recurring users the same way, I had some differences in the stats. What’s important is that they were close enough to be considered similar in both tools.

Since I was happy with the new tool, I went for a paid plan to make my life easier. No regret so far. I mostly look at stats once a month with their monthly email report anyway.

Before shutting down Matomo completely, I wanted to export data I had it it. To do this, I used the small Python script below. It took me a bit of time to write and required some trial and errors on my end, so I want to share it in case you are doing something similar. I didn’t bother importing the data in Plausible: most of it is old and I only want to keep it as archive.

import requests
from datetime import date
from dateutil.relativedelta import *

# Replace with your values
api_url = ""  # In my case: https://piwik.jujens.eu/index.php
auth_token = ""
start_date = date(2015, 1, 1)
end_date = date(2024, 12, 31)

# That's the tricky part. Matomo has an API, and I thought I’d be able to do GET
# request to it to get my data. It failed. I tried the POST API with a dict
# and it fail again.
# In the end, the solution I found it to split the suggested GET parameters,
# put it in a dict and do post requests to the API.
dd = "module=API&format=CSV&idSite=1&period=month&date=2024-12-01&method=Actions.getPageTitles&expanded=1&translateColumnNames=1&language=en&token_auth=XXXXX&filter_limit=-1".split("&")
data = {key: value for key, value in list(d.split("=") for d in dd)}

d = start_date
while d < end_date:
    data["date"] = d
    with open(f"page_views_{d.isoformat()}.csv", "wb") as f:
        f.write(requests.post(api_url, data=data).content)
    d += relativedelta(months=1)

From ZSH to Fish

2021-11-07T00:00:00+01:00

After several years of ZSH with oh-my-zsh, I decided to give fish (Friendly Interactive Shell). I heard and read several good things about it. I also wanted to test starship (a cross shell prompt) easily without messing with my ZSH configuration.

The least I can say is: I'm impressed. Most of the niceties that ohmyzsh brings simply work out of the box: better history, better completion, syntax coloring… Since Fish don't use the standard shell syntax, I had to port some of my functions to get a usable shell. I must admit the changes made by Fish, although a bit hard to get used to after so many years, are really nice and make syntax clearer. And you can document them!

Regarding starship, it provides a lot of configuration and options but the default are very good. Again, the migration was swift and painless. I merely disabled the AWS and GCP plugins to avoid cluttering my shell with data I don't often need to get the same behavior as my old ZSH configuration.

To conclude, I'm impressed and very satisfied with my migration. It went smoothly and most tools (like starship or git) are compatible with it. I still have to read the doc from time to time and unlearn years of bashism. Since Fish is not widespread (yet?), I still use Bash more the scripts that must be shared with other people.

Small API to manage packages

2021-07-10T00:00:00+02:00

At last, here is my follow up to small TODO apps where I created a small CLI TODO app in Rust, Clojure and Haskell to test functional (or functional like) programming languages. Like I said in my previous article, I also wanted to see how these languages behave for the web.

So I decided to create the same API four times: first in Python with Django to have a starting point (that's the tech I'm most at ease with) then in Rust, Clojure and Haskell. This API must be able to add a package, list all packages and search for a given package by name. The creation of a package should be protected by authentication. In the end, I only reached this full scope with Django. I removed authentication in Rust and Clojure to gain time.

As for Haskell, I completely dropped it: I tried the frameworks Yesdo and Servant. I had issues to compile the quickstart project with both of them. I managed to get Servant to work, but struggled with database access. I also found it difficult to get back in Haskell after such a long time. I could have searched more or reached for help on an Haskell forum, but the amount of time I was willing to dedicate to this exercise was running out. So I dropped Haskell and moved on.

All the code is available in my gitlab. In each project, you'll find a README that explains how to launch and use the project. Like in my previous post, I'll go over the main characteristics of each implementation and then try to conclude.

Contents

Python and Django
Rust and actix
Clojure and Luminus
Summary

Python and Django

I wrote the first implementation in Django and Django Rest Framework to have a base implementation I could compare against.

The project is separated in different apps like in all Django project. It's not strictly necessary for a project so small, but it's how you do things. I based the project on the official tutorial instead of something more complete (like this generator) to keep things simple. I merely changed the app organization a bit to have something a bit more structured. In the end, I have two apps: core to manage users and their authentication and packages for the packages.

My code is structured around three concepts:

The model for database access.
The serializer to transform the model into JSON and validate inputs when we create a new package.
The view to glue everything together. It receives the HTTP request, creates the serializer, appends the current user id to the data when we create a package and filters the data when we do a search. The filters part could have been extracted elsewhere but it felt overkill for such a simple project.

While writing the apps, I wandered what it would be like if I search with a % (it has a special meaning in SQL) character in the same like 100%. I created a package named To 100% and beyond and one named Over 100°C water and search for articles that contained 100% (yes, those names are silly for packages). Django ORM correctly and automatically escaped % from my input and the view only returned the To 100% and beyond package.

Rust and actix

For my Rust version I decided to use the actix mostly because I already used it a bit in the past. I was also able to read the example project sqlx-todo which uses the same tech I did: rust, actix and a sqlite database.

While I could have used an ORM with actix, I decided not to: I wanted to test a bit of async and await in Rust and at this time no ORM is compatible with this programming method.

I rely on custom Shell scripts to create the database and its tables. It's more than enough for my small test. Since I have the same usage as the Django version, I relied on Django to generate the SQL. And since I initially planned to add authentication, I create a table for users and a link between users and packages. To simplify my implementation, instead of removing this, I decided to create a sample user which will own all the packages. This way, from the database perspective, I'm closer to the Django version.

The code is divided in two files:

main.rs which contains all the view logic.
model.rs where the struct representing a package (the struct can be serialized and deserialized easily with a lib named serde) and all the logic relating to the database.

Overall, the experience was pleasing. There's less boilerplate than in any other version which makes the project easier to understand when you get started. On the downside, it's up to you to organize things correctly when the project grows. The sqlx-todo project also helped me to start correctly faster, which was nice. The only real pain point I had was to correctly serialize the package creation date time: there is documentation on how to do that with the chrono library but I struggled to put it all together like I wanted.

Finally, to answer my question: how does it behave by default with % in the input, I reproduced the steps of the Django version. The answer is: by default % won't be escaped and will behave as the special SQL character it is. It's logical you have to do it yourself since you build the actual query yourself.

Clojure and Luminus

For Clojure, I decided to use the Luminus framework because it's easy to get started with it. leinigen (an automation tool for Clojure) makes it really easy to generate a project configured to use a SQLite database. The downside is: the generated project is quite big and for a newbie like me, it's easy to get lost in all this (like a newbie to Django would be I guess).

Luminus has an integrated migration system based on manually written SQL files. So I used that to create my table, once again thanks to SQL generated by Django from its models. All those files are in clj_luminus/resources/migrations/. There is always a .up.sql file to apply the migration and a .down.sql to revert it if needed.

Creating a simple view to list package is simple enough as you can see in clj_luminus/src/clj/clj_luminus/routes/api.clj (function list-packages). It can then easily be linked in the router. What I find peculiar, is how Luminus handles SQL queries:

You write all your queries in a file named clj_luminus/resources/sql/queries.sql.
Above the query, you give it a name and describe what it does (query, update, insert) in a comment.
Based on that, HugSQL (the library used by Luminus to do its SQL requests) will automatically create a function to actually do the query.

It's a bit strange when you are not used to it, but it works quite well. The big downside I didn't manage to overcome though: while a change in the code is immediately reflected in the project and is available with a simple page refresh, changing a SQL query always required me to restart the project. And project startup in Clojure is slow which is a pain. For a serious project, this would be a big downside. I guess there is a work around and my problem is just I didn't find it.

I also struggled a bit to create a package:

I add to manually add a middleware so the posted JSON would be correctly parsed. That was not obvious at first.
I'm not convinced by how I pass the date of creation. I think it could fail on a stricter database than SQLite.
Getting the last inserted ID was way harder than I though. According to the documentation, there is a way to get it, I can see it in the returned data under a key :last_insert_rowid() but I never managed to access it. In the end, I converted the map into a vector and read the proper index from the vector. It's a bit ugly, but it works.
Unlike with Django and Rust where the data is validated out of the box in the serializer or the struct, I had to do it manually here. It's not a big deal, but you must think of it when you are used to other tools.

To answer my question: how does it behave by default with % in the input, I again reproduced the steps of the Django version. The answer is, just like for Rust: by default % won't be escaped and will behave as the special SQL character it is. Again, it's logical you have to do it yourself since you build the actual query yourself.

Before concluding, I'd like to point out that although I didn't add authentication because I lacked time, Luminus provides tooling to add it out of the box. So it should be fairly straightforward.

Summary

To conclude, I'll say I enjoyed writing these small apps and too see different languages and ways to do things. I felt the most at ease with Django since it's the framework I work with day to day. Rust is fun, the compiler does its best to help you and you can find many resources online. The language (at least the bases, the language itself is actually quite big and complex) is also fairly easy to pick up if you have a programming background. Clojure is fun, there are some good projects and tooling out there, although the documentation could sometimes be better. Since it barely has any syntax, you can forget functions of the standard library after a while but not how to write code in it, despite how different it is from other languages. And Haskell, well, it's probably the language that I would benefit most from learning: it's very different to what I know and its approach probably would make me a better developer. However, it's hard to pick up with its syntax and type system, even with a programming background. And after a while, I forgot most of it. I don't want to dedicate time for it now, so I won't dig any further.

Use a dedicated user to run your database migrations on PostgreSQL

2021-03-10T00:00:00+01:00

I'll detail here how to use one user to apply your migrations and one to run you site. This method can be applied to any framework and environment as long as your database is PostgreSQL. It's of course possible to do with other databases, but the SQL syntax to achieve this will be different.

Before beginning, let's see why we would want to do this:

Increased security: by limiting the database operations your site is allowed to make, you reduce the attack surface by applying the principle of least privilege. Please note that I am only talking about schema updates: your site still needs to do SELECT, INSERT, UPDATE and DELETE to work correctly. So, you only limit the surface of attack. If an attacker were to gain access to your database, they would still be able to steal or destroy data. You thus still need proper protection on your database with SSL, strong passwords and possibly access limitation (like IP whitelisting).
Reduced error capabilities: if you are to execute some queries (to debug or analyze something) in your production database, you cannot alter the schema. So if you do make mistakes, they shouldn't be too serious. Please understand that I don't advise you to run queries directly on your production database (your site with its peer-reviewed code is there for it), but you can need it from time to time.

How can we achieve this? Let's dive in. You can launch all these commands in a container if you want to try them out. That's what I did to write this tutorial. All my psql commands are written with that in mind, please adapt them if you must connect differently to your database.

To begin with, we must create the user that will apply our migrations. Let's call it sqlmigrations. We could use the postgres user for this, but I think it's better to have a dedicated user without the super privilege role for the reasons explained above. To do this, connect to the database with psql -U postgres and run:
```
CREATE ROLE sqlmigrations WITH LOGIN CREATEDB CREATEROLE;
```
LOGIN is required to allow us to use this user to connect to a database, CREATEDB will allow us to create a database that will be owned by sqlmigrations and CREATEROLE will allow us to create the other user with sqlmigrations. This way, all our objects will have the proper owner which will make our lives easier: since everything we need to operate on belongs to sqlmigrations we can use this user for all our operations. You could reduce the permissions of sqlmigrations to limit its scope further, it's just a bit more complex and I won't detail this here. With all the information here, you would be able to do this easily if you want.
Now that our user is created, we can exit the first command prompt with \q and connect with our new user with:
```
psql -U sqlmigrations -d postgres
```
Since no database exists with the name sqlmigrations we need to specify another existing database like the default postgres. If we don't, our connection will fail with psql: FATAL: database "sqlmigrations" does not exist.
Now, let's create our database:
```
CREATE DATABASE djangosite;
```
We can now connect to our database with:
```
psql -U sqlmigrations -d djangosite
```

Let's create the user for our site:

CREATE ROLE django WITH LOGIN;

If you use the \du command to list our users, you should see this at this point:

Role name   |                         Attributes                         | Member of
---------------+------------------------------------------------------------+-----------
django        |                                                            | {}
postgres      | Superuser, Create role, Create DB, Replication, Bypass RLS | {}
sqlmigrations | Create role, Create DB

Now, let's give the proper roles to our django user. This always happen in two steps: we apply the change on existing objects then we alter the default options to enforce our rules to new objects. If you have multiple schemas, you will have to repeat the operation for all of them. Here, I only cover the public schema.

-- Allow our user to run SELECT, INSERT, UPDATE, DELETE queries.
GRANT SELECT, INSERT, UPDATE, DELETE
    ON ALL TABLES
    IN SCHEMA public
    TO django;
-- Enable this for all new tables.
ALTER DEFAULT PRIVILEGES
    GRANT SELECT, INSERT, UPDATE, DELETE
    ON TABLES
    TO django;
-- Allow our user to use SEQUENCES.
-- It's required to insert data with auto-incrementing primary keys for instance.
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO django;
ALTER DEFAULT PRIVILEGES
    GRANT USAGE, SELECT
    ON SEQUENCES
    TO django;

So far, so good. We are not completely done yet however. Our django user still can alter its permission which we don't want: what's the point of limiting what a user can do if it can do privilege escalation? We can avoid this with:

REVOKE GRANT OPTION
    FOR ALL PRIVILEGES
    ON ALL TABLES
    IN SCHEMA public
    FROM django;
ALTER DEFAULT PRIVILEGES
    REVOKE GRANT OPTION
    FOR ALL PRIVILEGES
    ON TABLES
    FROM django;

Last step, we must prevent our django user to be able to create table (which is possible by default). We need to do this in three steps (as far as I know, it's the only way to do this):
1. Connect to the database with the postgres user (only a super user can do this):
```
psql -U postgres -d djangosite
```
2. Revoke the ability to create tables for all users:
```
-- public (lower case) is for the schema public.
-- PUBLIC (upper case) means "for all users".
REVOKE CREATE ON SCHEMA public FROM PUBLIC;
```
3. Grant back the ability to create table to the sqlmigrations user (again, only a super user can do this):
```
GRANT CREATE ON SCHEMA public TO sqlmigrations;
```

Now that we've done all that, let's test it:

As sqlmigrations, you should be able to do what you want. For instance:

djangosite=> CREATE TABLE tata(id INTEGER);
CREATE TABLE
djangosite=> ALTER TABLE toto ADD COLUMN toto TEXT;
ALTER TABLE
djangosite=> ALTER TABLE toto DROP COLUMN toto;
ALTER TABLE

But the user django has restricted access (connect with psql -U django -d djangosite):

djangosite=> SELECT * FROM toto;
id
----
(0 rows)

djangosite=> INSERT INTO toto VALUES (1);
INSERT 0 1
djangosite=> SELECT * FROM toto;
id
----
1
(1 row)

djangosite=> ALTER TABLE toto ADD COLUMN toto TEXT;
ERROR:  must be owner of table toto
djangosite=> DROP TABLE toto;
ERROR:  must be owner of table toto
djangosite=> CREATE TABLE dj(id INTEGER);
ERROR:  permission denied for schema public
LINE 1: CREATE TABLE dj(id INTEGER);
                    ^
djangosite=> DELETE FROM toto WHERE id = 1;
DELETE 1
djangosite=> SELECT * FROM toto;
id | tata
----+------
2 |
(1 row)

To view a summary of all permissions, run:

djangosite=> \ddp
                    Default access privileges
    Owner     | Schema | Type  |          Access privileges
---------------+--------+-------+-------------------------------------
sqlmigrations |        | table | sqlmigrations=arwdDxt/sqlmigrations+
            |        |       | django=arwd/sqlmigrations
(1 row)

djangosite=> \dp
                                    Access privileges
Schema | Name | Type  |          Access privileges          | Column privileges | Policies
--------+------+-------+-------------------------------------+-------------------+----------
public | toto | table | sqlmigrations=arwdDxt/sqlmigrations+|                   |
    |      |       | django=arwd/sqlmigrations           |                   |
(1 row)

Bonus: if you created everything as the postgres user and want to change to another user, you will have to change the owner of the database and its tables with:

ALTER DATABASE djangosite OWNER TO sqlmigrations;
-- Repeat for each table
ALTER TABLE toto OWNER TO sqlmigrations;

You cannot use REASSIGN OWNED BY postgres TO sqlmigrations; to gain time because PostgreSQL doesn't allow you to do that for objects that belongs to the user postgres (it would mess up PG since many system objects are owned and must be owned by the user postgres).

Some resources:

Small TODO apps

2021-03-06T00:00:00+01:00

I recently decided to lean a bit of Haskell for fun and see what the language was like. In this context, I decided to create a small TODO app. Since I also wanted to compare my solution with solutions in other languages, I decided to write the TODO app three times:

In Haskell to practice the language as well as monads.
In Rust because I like the language.
In Clojure because I already knew it and I wanted to practice it. It's a functional language like Haskell, so I though it would be interesting to include it in the comparison.

Each app will do the exact same thing:

Initialize the database on startup, this means create the SQLite file and the table todo if required. This way, we can easily use it later.
Allow the database file to be specified to use a specific file if needed.
Store new TODO items in the database. Each TODO will be made of an id, a title and a completion status (ie done or not done).
List all TODOs.
Insert test data in the database.
Mark a TODO as done.

I'll talk a bit about each app and then try to conclude my experience. I'll start with the Rust one, then the Clojure one and finally the Haskell one (that's the order in which I wrote them). You will find the full source code in each section.

Rust

Rust is the language that most alike to the languages I use everyday: Python and JavaScript. The goal of the language is to write fast and memory safe code without the need for a garbage collector. It's done thanks to its compiler and its type system (which I won't explain here). The errors of the compiler are generally explicit and clear. While it borrows some concepts from functional programming like immutability by default or if expressions, we can still write procedural or object like code. We also have to make some variables mutable from time to time (which is not possible in functional programming languages). So it's a mix, but an efficient one if you ask me.

I also think the community is striving and I found without any difficulty many libraries to parse command line arguments or communicate with the database. I settled with clap for argument parsing and rusqlite for SQLite communication. They both seems like popular and robust choices for what I was aiming for while staying simple to use.

Now, let's talk about the code itself. The definition of the parser resembles what I could do in Python or JS, as you can see with the code sample below. I also find it very readable and expressive.

let matches = App::new("Todo application")
    .author("Jujens <jujens@jujens.eu>")
    .about("Small app to manage todos in a local SQLite database.")
    .setting(AppSettings::SubcommandRequiredElseHelp)
    .arg(
        Arg::with_name("file")
        .long("file")
        .takes_value(true)
        .default_value(DEFAULT_DB_PATH)
        .help("Path to the database.")
    )
    .subcommand(
        App::new("insert-test-data")
        .about("Insert test TODOs in the database")
    );

Since I have 4 different actions with different arguments, I decided to divide the code in subcommands. A pattern I reused for all apps.

If creating the parser is very similar to what I could have done in Python, when I had to use it, I saw some particularities of Rust: Rust doesn't have exceptions and forces you to handle all errors. For instance, when I create a TODO in handle_create, I pass a title with the --title option. Since the argument may not be provided, I get an Option from the parser: it's a data structure used in Rust to handle optional values, like Maybe in Haskell. When you have this structure, you need to extract the value from it before you can use it which forces you to handle the case where you have a value and the case where you haven't one. So the compiler, forces you to handle potential missing data. There is also a similar structure named Result which holds a value or an error. It's useful when you need to provide a useful error message and not just a value or None.

This is how it looks like:

let title = match matches.value_of("title") {
    Some(title) => title,
    None => {
        println!("You must supply a title for the match");
        exit(1);
    },
};

This is very interesting and allowed me to provide custom and precise error messages at each step. But, this makes the code quite verbose. To help a bit, you can use things like unwrap (which can result in a crash if the structure doesn't hold a value) or unwrap_or to extract the value or get a default value if needed. You can also use the ? operator like that:

conn.execute("INSERT INTO todo (title, is_done) VALUES (?1, ?2)", params![title, false])?;

The compiler will propagate the error, meaning the compiler will replace the code above by:

let value = match conn.execute("INSERT INTO todo (title, is_done) VALUES (?1, ?2)", params![title, false]) {
    Ok(value) => value,
    Err(e) => return Error(e),
};

which is much more compact and achieve the same result if you don't want/need to handle the error at call site. That's a very nice syntactic sugar I didn't used much to handle errors in order to provide the user with relevant messages.

The thing to remember (from my perspective at least) is that you can write code that crash at runtime if you don't pay attention or don't know what you are doing. The language will just give you tools to avoid this, it's then up to you to use those tools correctly.

Since all my other commands are written in the same way, I won't detail more: I think I have given you the gist of the code. To dig deeper, here is my Cargo.toml file with the project dependencies:

 1 [package]
 2 name = "todos"
 3 version = "0.1.0"
 4 authors = ["Julien Enselme <jenselme@jujens.eu>"]
 5 edition = "2018"
 6 
 7 [dependencies]
 8 clap = "2.33.3"
 9 
10 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
11 
12 [dependencies.rusqlite]
13 version = "0.24.2"
14 features = ["bundled"]

and the full src/main.rs file:

  1 use std::path::Path;
  2 use std::process::{ exit };
  3 
  4 use clap::{Arg, App, AppSettings, ArgMatches};
  5 
  6 use rusqlite::{params, Connection, Result};
  7 use rusqlite::NO_PARAMS;
  8 
  9 #[derive(Debug)]
 10 struct Todo {
 11     id: i32,
 12     title: String,
 13     is_done: bool,
 14 }
 15 
 16 fn main() {
 17     const DEFAULT_DB_PATH: &str = "./todos.db";
 18     let matches = App::new("Todo application")
 19         .author("Jujens <jujens@jujens.eu>")
 20         .about("Small app to manage todos in a local SQLite database.")
 21         .setting(AppSettings::SubcommandRequiredElseHelp)
 22         .arg(
 23             Arg::with_name("file")
 24             .short("f")
 25             .long("file")
 26             .takes_value(true)
 27             .default_value(DEFAULT_DB_PATH)
 28             .help("Path to the database.")
 29         )
 30         .subcommand(
 31             App::new("insert-test-data")
 32             .about("Insert test TODOs in the database")
 33         )
 34         .subcommand(
 35             App::new("list")
 36             .about("List all TODOs from the database")
 37         )
 38         .subcommand(
 39             App::new("create")
 40             .about("Create a new TODOs")
 41             .setting(AppSettings::ArgRequiredElseHelp)
 42             .arg(
 43                 Arg::with_name("title")
 44                 .short("t")
 45                 .long("title")
 46                 .takes_value(true)
 47                 .required(true)
 48                 .multiple(false)
 49                 .help("The title of the TODO to use.")
 50             )
 51         )
 52         .subcommand(
 53             App::new("complete")
 54             .about("Mark a TODO as done")
 55             .setting(AppSettings::ArgRequiredElseHelp)
 56             .arg(
 57                 Arg::with_name("id")
 58                 .required(true)
 59                 .help("The ID of the TODO to complete.")
 60             )
 61         )
 62         .get_matches();
 63 
 64     let mut conn = match init(matches.value_of("file").unwrap_or(DEFAULT_DB_PATH)) {
 65         Ok(conn) => conn,
 66         Err(e) => {
 67             println!("An error occurred while initializing the database: \"{}\".", e);
 68             exit(1);
 69         },
 70     };
 71 
 72     match matches.subcommand() {
 73         ("insert-test-data", _) => handle_insert_test_data(&mut conn),
 74         ("list", _) => handle_list_all(conn),
 75         ("create", creation_matches) => handle_create(conn, creation_matches),
 76         ("complete", Some(complete_matches)) => handle_complete(conn, complete_matches),
 77         _ => {
 78             println!("No valid subcommand was used");
 79             exit(1);
 80         },
 81     }
 82 }
 83 
 84 fn init(db_path: &str) -> Result<Connection> {
 85     if Path::new(db_path).exists() {
 86         return Ok(create_connection(db_path)?);
 87     }
 88 
 89     let conn = create_connection(db_path)?;
 90     conn.execute("CREATE TABLE IF NOT EXISTS todo (id integer primary key, title text not null, is_done boolean not null)", NO_PARAMS)?;
 91 
 92     return Ok(conn);
 93 }
 94 
 95 fn create_connection(db_path: &str) -> Result<Connection> {
 96     return Connection::open(db_path);
 97 }
 98 
 99 fn handle_insert_test_data(conn: &mut Connection) {
100     match insert_test_data(conn) {
101         Ok(()) => {},
102         Err(e) => {
103             println!("An error occurred while inserting test data: \"{}\"", e);
104             exit(1);
105         }
106     }
107 }
108 
109 fn insert_test_data(conn: &mut Connection) -> Result<()> {
110     let tx = conn.transaction()?;
111 
112     tx.execute("DELETE FROM todo;", NO_PARAMS).unwrap();
113     tx.execute("INSERT INTO todo (title, is_done) VALUES (?1, ?2)", params!["Start project", true])?;
114     tx.execute("INSERT INTO todo (title, is_done) VALUES (?1, ?2)", params!["Complete project", false])?;
115 
116     return tx.commit();
117 }
118 
119 fn handle_list_all(conn: Connection) {
120     match list_all(conn) {
121         Ok(results) => display_all(results),
122         Err(e) => {
123             println!("An error occurred while listing all todos: \"{}\".", e);
124             exit(1);
125         }
126     }
127 }
128 
129 fn display_all(todos: Vec<Todo>) {
130     for todo in todos.iter() {
131         println!("- id: {}, title: \"{}\", done: {}", todo.id, todo.title, todo.is_done);
132     }
133 }
134 
135 fn list_all(conn: Connection) -> Result<Vec<Todo>> {
136     let mut stmt = conn.prepare("SELECT id, title, is_done FROM todo")?;
137     let todos_iter = stmt.query_map(NO_PARAMS, |row| {
138         Ok(Todo {
139             id: row.get(0)?,
140             title: row.get(1)?,
141             is_done: row.get(2)?,
142         })
143     })?;
144 
145     let mut todos = vec![];
146     for todo_result in todos_iter {
147         match todo_result {
148             Ok(todo) => todos.push(todo),
149             Err(e) => println!("Error while fetching some todos: \"{}\".", e),
150         }
151     }
152 
153     return Ok(todos);
154 }
155 
156 fn handle_create(conn: Connection, create_matches: Option<&ArgMatches>) {
157     let matches = match create_matches {
158         Some(matches) => matches,
159         None => {
160             println!("You must supply a title for the match.");
161             exit(1);
162         }
163     };
164     let title = match matches.value_of("title") {
165         Some(title) => title,
166         None => {
167             println!("You must supply a title for the match");
168             exit(1);
169         },
170     };
171 
172     match create(conn, title) {
173         Ok(()) => {},
174         Err(e) => {
175             println!("An error occurred while creating a new TODO: \"{}\"", e);
176             exit(1);
177         }
178     };
179 }
180 
181 fn create(conn: Connection, title: &str) -> Result<()> {
182     conn.execute("INSERT INTO todo (title, is_done) VALUES (?1, ?2)", params![title, false])?;
183 
184     return Ok(());
185 }
186 
187 fn handle_complete(conn: Connection, complete_matches: &ArgMatches) {
188     let raw_id = match complete_matches.value_of("id") {
189         Some(raw_id) => raw_id,
190         None => {
191             println!("You must supply an id");
192             exit(1);
193         }
194     };
195 
196     let id = match raw_id.parse::<u32>() {
197         Ok(id) => id,
198         Err(e) => {
199             println!("You must supply a valid ID (an interger): \"{}\"", e);
200             exit(1);
201         }
202     };
203 
204     match complete(conn, id) {
205         Ok(()) => {},
206         Err(e) => {
207             println!("An error occurred while completing the TODO {}: \"{}\"", id, e);
208         }
209     }
210 }
211 
212 fn complete(conn: Connection, id: u32) -> Result<(), String> {
213     let nb_rows_updated = conn.execute("UPDATE todo SET is_done = ?1 WHERE id = ?2", params![true, id]);
214 
215     return match nb_rows_updated {
216         Ok(0) => Err(format!("No row found for supplied id: {}.", id)),
217         Err(e) => Err(format!("{}", e)),
218         _ => Ok(()),
219     };
220 }

Clojure

Clojure is very different. It's a LISP where all the code is written as lists (like in all LISPs) that runs on the JVM. All data structures are immutable and variables are dynamically typed. The language aims to focus on the data instead of the program.

It was easy to find libraries but I found that the parser was less complete than the Rust or Haskell one (or Python ones for that matter). I guess it comes from the fact that Clojure is a niche language that is less known and has a smaller community.

I had more manual work to do to parse my arguments, including the validation. I think that when you are not used to the language or another LISP, the program is hard to decode with everything having the same structure. Since it's also very different, it's also way harder to understand if you don't already know the language.

I defined the options of the parser in a vector (similar to a list in Python):

(def cli-options
    [["-f" "--file PORT" "Path to the database file to use."
    :default "./todos.db"]
    ["-h" "--help"]])

I can then use this with the parse-opts function to extract my arguments (and potential errors):

(let [{:keys [options arguments errors summary]} (parse-opts args cli-options :in-order true)]
    "The code")

The parse-opts function will return a map (a dict in Python), the :keys allows me to extract values from this map (options, argument…) and the let expression allows me to bind these values to local variables (with the same name they had in the map). I can then use these values to build a map either to exit the program later with a message or to execute actual code based on the supplied arguments. I used a similar pattern to define and parse the options of my subcommands.

I won't detail much here since I think it would take too much time to teach Clojure here. I just say that all the fonctions themselves are way shorter than in the Rust version since I could easily handle all exceptions globally with a catch handler (Clojure relies on exception for errors). The price is: I'm less precise in the messages I give. But I could avoid this by adding more catch handlers at the price of verbosity. I'll also point out that all functions that ends with an exclamation mark like insert! mutate the sate by convention and must not be confused by by the exclamation mark used to identify macros in Rust. With that, you should be able to get a high level understanding of what the program does.

Like above, here is my project.clj with project dependencies:

 1 (defproject todo "0.1.0-SNAPSHOT"
 2   :description "FIXME: write description"
 3   :url "http://example.com/FIXME"
 4   :license {:name "EPL-2.0 OR GPL-2.0-or-later WITH Classpath-exception-2.0"
 5             :url "https://www.eclipse.org/legal/epl-2.0/"}
 6   :dependencies [[org.clojure/clojure "1.10.1"]
 7                  [org.clojure/tools.cli "1.0.194"]
 8                  [org.clojure/java.jdbc "0.7.12"]
 9                  [org.xerial/sqlite-jdbc "3.34.0"]]
10   :main ^:skip-aot todo.core
11   :target-path "target/%s"
12   :profiles {:uberjar {:aot :all}})

and my src/todo/core.clj source file:

  1 (ns todo.core
  2   (:require [clojure.tools.cli :refer [parse-opts]]
  3             [clojure.string :as string]
  4             [clojure.java.jdbc :as jdbc])
  5   (:gen-class)
  6   (:import (clojure.lang ExceptionInfo)))
  7 
  8 (def allowed-commands #{"insert-test-data", "list", "create", "complete"})
  9 
 10 (def command->options {
 11                        "insert-test-data" [["-h" "--help"]]
 12                        "list" [["-h" "--help"]]
 13                        "create" [["-h" "--help"]
 14                                  ["-t" "--title TITLE" "The title of the todo"]]
 15                        "complete" [["-h" "--help"]
 16                                    [nil "--id ID" "The ID of the TODO to mark as done"
 17                                     :parse-fn #(Integer/parseInt %)]]
 18                        })
 19 
 20 (def command->desc {
 21                        "insert-test-data" "Insert test TODOs into the database"
 22                        "list" "List all TODOs from the database"
 23                        "create" "Create a new TODO"
 24                        "complete" "Mark the TODO as done"
 25                        })
 26 
 27 (def cli-options
 28   [["-f" "--file PORT" "Path to the database file to use."
 29     :default "./todos.db"]
 30    ["-h" "--help"]])
 31 
 32 (defn- usage [options-summary]
 33   (->> ["This is a sample TODO program to create and update TODOs"
 34         "Usage: todo [options] COMMAND [command-options]"
 35         ""
 36         "Options:"
 37         options-summary
 38         ""
 39         "Commands:"
 40         (string/join \newline allowed-commands)]
 41        (string/join \newline)))
 42 
 43 (defn- error-msg [errors]
 44   (str "The following errors occurred while parsing your command:\n"
 45        (string/join \newline errors)))
 46 
 47 (defn- exit [status msg]
 48   (println msg)
 49   (System/exit status))
 50 
 51 (defn- command-usage [command summary]
 52   (string/join \newline [(command->desc command) summary]))
 53 
 54 (defn- validate-command-args
 55   "Validate arguments for each subcommands"
 56   [args global-options]
 57   (let [command (first args)
 58         command-args (rest args)
 59         {:keys [options arguments errors summary]} (parse-opts args (command->options command))]
 60     (cond
 61       errors {:exit-message (error-msg errors) :ok? false}
 62       (:help options) {:exit-message (command-usage command summary) :ok? true}
 63       :else {:command command :options options :global-options global-options})))
 64 
 65 (defn- validate-args
 66   "Validate command line arguments. Either return a map indicating the program
 67   should exit (with a error message, and optional ok status), or a map
 68   indicating the action the program should take and the options provided."
 69   [args]
 70   (let [{:keys [options arguments errors summary]} (parse-opts args cli-options :in-order true)]
 71     (cond
 72       (:help options) {:exit-message (usage summary) :ok? true}
 73       errors {:exit-message (error-msg errors) :ok? false}
 74       (and (<= 1 (count arguments))
 75            (allowed-commands (first arguments))) (validate-command-args arguments options)
 76       :else {:exit-message (usage summary)})))
 77 
 78 (defn- insert-test-data
 79   [db]
 80   (jdbc/insert-multi! db :todo
 81                       [:title :done]
 82                       [["Start the project" true]
 83                        ["Complete the project" false]]))
 84 
 85 (defn- display-todo
 86   [todo]
 87   (->> [(str "- id: " (:id todo))
 88         (str "title: " (:title todo))
 89         (str "done: " (if (= (:done todo) 1) "true" "false"))]
 90        (string/join ", ")
 91        (println)))
 92 
 93 (defn- list-all
 94   [db]
 95   (let [rows (jdbc/query db ["SELECT id, title, done FROM todo"])]
 96     (doseq [todo rows]
 97       (display-todo todo))))
 98 
 99 (defn- create
100   [conn options]
101   (if-let [title (:title options)]
102     (jdbc/insert! conn :todo {:title title :done false})
103     (exit 1 (error-msg ["You must supply a title with --title"]))))
104 
105 (defn- complete
106   [conn options]
107   (if-let [id (:id options)]
108     (let [nb-rows-updated (first (jdbc/update! conn :todo {:done true} ["id = ?" id]))]
109       (if (not (= nb-rows-updated 1))
110         (exit 1 (str "No rows could be found for id " id))))
111     (exit 1 (error-msg ["You must supply the id of the TODO with --id"]))))
112 
113 (defn- init
114   [db]
115   (jdbc/db-do-commands db
116                        (jdbc/create-table-ddl :todo [[:id :integer :primary :key]
117                                                      [:title :text "not null"]
118                                                      [:done :boolean :default false "not null"]]
119                                               {:conditional? true})))
120 
121 (defn- run
122   [global-options command options]
123   (let [db {:classname   "org.sqlite.JDBC"
124             :subprotocol "sqlite"
125             :subname     (:file global-options)}]
126     (jdbc/with-db-transaction [conn db]
127                               (try
128                                 (init conn)
129                                 (case command
130                                   "insert-test-data" (insert-test-data conn)
131                                   "list" (list-all conn)
132                                   "create" (create conn options)
133                                   "complete" (complete conn options))
134                                 (catch Exception ex
135                                   (println
136                                     "An exception occurred while performing " command
137                                     " with options " options
138                                     " and global options " global-options
139                                     ": "
140                                     (.getMessage ex)))))))
141 
142 (defn -main
143   [& args]
144   (let [{:keys [command options global-options exit-message ok?]} (validate-args args)]
145     (if exit-message
146       (exit (if ok? 0 1) exit-message)
147       (run global-options command options))))

Haskell

Haskell is also very different from other languages I normally use and it's often cited as the reference of functional languages. In Haskell, functions are more like mathematical functions, all variables are immutable and all side effects are encapsulated to maintain function purity. It also relies on indentation to express the code and don't need semi-colon or curly braces or to wrap everything in parentheses. The type system is very expressive and is a bit hard to read and understand when you start (mostly when many Monads are involved in functions signatures). Like for Clojure, I'll analyse part of the code but won't attempt to teach you Haskell.

The parsing of the arguments relies heavily on the type system and on the combination of function. For instance, to parse the title used to create a TODO, first I create a union type to hold all the commands (deriving Show is an easy way to be able to print the data):

data Command =
    List
    | InsertTestData
    | Create CreateOptions
    | Complete CompleteOptions
    deriving Show

Then, I create a type named CreateOptions to hold the options:

data CreateOptions = CreateOptions { title :: String }

then a function to parse the option themselves:

createOptionsParser :: Parser CreateOptions
createOptionsParser = CreateOptions
    <$> strOption (long "title" <> short 't' <> help "The title of the TODO." <> metavar "TITLE")

That's readable but to really understand what is going on you need to understand what <$> and <> do which isn't simple and which I won't explain there.

I can then create the parser for the command itself:

createParser :: Parser Command
createParser = Create <$> createOptionsParser

which can then be used in the subcommand parser.

The arguments will be parsed in a do block to handle side effects (another important point I won't explain).

The most interesting part is the use of pattern matching to run the proper command based on the actual type of the parsed command:

runCommand :: Command -> Connection -> IO ()
runCommand List = listAll
runCommand InsertTestData = insertTestData
runCommand (Create CreateOptions { title = title }) = createTodo title
runCommand (Complete CompleteOptions { todoId = todoId }) = completeTodo todoId

The parser will create a Command type of "type" List, Create… and we will use this syntax to execute specific code depending on the actual type of the command and extract their parameters with destructuring. I find that very expressive and concise. And it avoids to have complex if or case. I also note that with its usage of parenthesis, Haskell code sometimes makes me thing of LISP.

Now that I managed to parse the options, I can do things, for instance create a TODO:

createTodo :: String -> Connection -> IO()
createTodo title conn = do
    insertResult <- try (execute conn "INSERT INTO todo (title, is_done) values (?, ?)" (title, False :: Bool)) :: IO (Either SomeException ())
    case insertResult of
        (Left error) -> putStrLn $ "Failed to insert the todo: " ++ show error
        (Right result) -> pure ()

The way I handle the errors highly resemble how it's done in Rust. The try function is a way to catch the potential errors from the executed query. Without it, the code would crash if execute encountered an error. So yes, Haskell code can compile and crash at runtime if you don't pay attention (or don't know what you are doing) in some cases. I find that a bit weird given the preconception I had about the language which was all errors must be handled and if it compiles it works. To be fair, this can also happen in Rust, when you try to access an index that doesn't exist in a array or with invalid use of unwrap for instance. I guess no language is the silver bullet in that matter.

As usual, here's the code of my app/Main.hs file which serves as an entry point with parsing logic:

 1 {-# LANGUAGE BlockArguments #-}
 2 
 3 module Main where
 4 
 5 import Lib
 6 import Options.Applicative
 7 import Data.Semigroup ((<>))
 8 import Database.SQLite.Simple ( Connection )
 9 
10 data Options = Options GlobalOptions Command
11 
12 data GlobalOptions = GlobalOptions { file :: String } deriving Show
13 
14 data CreateOptions = CreateOptions { title :: String } deriving Show
15 
16 data CompleteOptions = CompleteOptions { todoId :: Int } deriving Show
17 
18 data Command =
19   List
20   | InsertTestData
21   | Create CreateOptions
22   | Complete CompleteOptions
23   deriving Show
24 
25 listParser :: Parser Command
26 listParser = pure List
27 
28 insertTestDataParser :: Parser Command
29 insertTestDataParser = pure InsertTestData
30 
31 createParser :: Parser Command
32 createParser = Create <$> createOptionsParser
33 
34 createOptionsParser :: Parser CreateOptions
35 createOptionsParser = CreateOptions
36   <$> strOption (long "title" <> short 't' <> help "The title of the TODO." <> metavar "TITLE")
37 
38 completeParser :: Parser Command
39 completeParser = Complete <$> completeOptionsParser
40 
41 completeOptionsParser :: Parser CompleteOptions
42 completeOptionsParser = CompleteOptions
43   <$> argument auto (metavar "ID" <> help "The ID of the todo to complete")
44 
45 globalOptionsParser :: Parser GlobalOptions
46 globalOptionsParser = GlobalOptions
47   <$> strOption (long "file" <> short 'f' <> help "Path to the database file." <> metavar "FILE" <> value "./todos.db")
48 
49 commandParser :: Parser Command
50 commandParser = hsubparser
51   (
52     command "list" (info listParser (progDesc "List all TODOs"))
53     <> command "insert-test-data" (info insertTestDataParser (progDesc "Add test TODOs in the database"))
54     <> command "create" (info createParser (progDesc "Create a new TODO."))
55     <> command "complete" (info completeParser (progDesc "Mark a TODO as done."))
56   )
57 
58 optionsParser :: Parser Options
59 optionsParser = Options
60   <$> globalOptionsParser
61   <*> commandParser
62 
63 main :: IO ()
64 main = run =<< execParser opts
65   where
66     opts = info (optionsParser <**> helper)
67       (fullDesc <> progDesc "Manage TODOs")
68 
69 run :: Options -> IO ()
70 run (Options globalOptions command) = do
71   conn <- initDb
72   runCommand command conn
73 
74 runCommand :: Command -> Connection -> IO ()
75 runCommand List = listAll
76 runCommand InsertTestData = insertTestData
77 runCommand (Create CreateOptions { title = title }) = createTodo title
78 runCommand (Complete CompleteOptions { todoId = todoId }) = completeTodo todoId

and the src/Lib.hs with the rest of the logic:

 1 {-# LANGUAGE DeriveGeneric #-}
 2 {-# LANGUAGE OverloadedStrings #-}
 3 
 4 module Lib
 5     ( listAll,
 6       initDb,
 7       insertTestData,
 8       createTodo,
 9       completeTodo,
10     ) where
11 
12 import GHC.Generics
13 import Control.Monad (forM, forM_)
14 import Prelude hiding (id)
15 import Control.Applicative
16 import Control.Exception
17 import Database.SQLite.Simple ( open, execute, executeNamed, execute_, query_, changes, withTransaction, Connection, NamedParam( (:=) ) )
18 import Database.SQLite.Simple.FromRow
19 
20 data Todo = Todo Int String Bool deriving (Generic, Show)
21 
22 -- The number of field here must match the number of fields we get from the SELECT.
23 instance FromRow Todo where
24   fromRow = Todo <$> field <*> field <*> field
25 
26 initDb :: IO Connection
27 initDb = do
28   conn <- open "./todos.db" -- The database file will be created if it doesn't exist.
29   execute_ conn "CREATE TABLE IF NOT EXISTS todo (id INTEGER PRIMARY KEY, title STR NOT NULL, is_done BOOLEAN NOT NULL)"
30   return conn
31 
32 insertTestData :: Connection -> IO ()
33 insertTestData conn = do
34     withTransaction conn $ replaceByTestData conn
35 
36 replaceByTestData :: Connection -> IO ()
37 replaceByTestData conn = do
38   execute_ conn "DELETE FROM todo;"
39   execute conn "INSERT INTO todo (title, is_done) values (?, ?)" ("Start project" :: String, True :: Bool)
40   execute conn "INSERT INTO todo (title, is_done) values (?, ?)" ("Complete project" :: String, False :: Bool)
41 
42 listAll :: Connection -> IO ()
43 listAll conn = do
44   todos <- try (query_ conn "SELECT id, title, is_done FROM todo;" :: IO [Todo]) :: IO (Either SomeException [Todo])
45   case todos of
46     (Left error) -> putStrLn $ "Failed to list all todos: " ++ show error
47     (Right allTodos) -> mapM_ (putStrLn . formatTodo) allTodos
48 
49 formatTodo :: Todo -> String
50 formatTodo (Todo id title isDone) = "- id: " ++ show id ++ ", title: " ++ show title ++ ", done: " ++ show isDone
51 
52 createTodo :: String -> Connection -> IO()
53 createTodo title conn = do
54   insertResult <- try (execute conn "INSERT INTO todo (title, is_done) values (?, ?)" (title, False :: Bool)) :: IO (Either SomeException ())
55   case insertResult of
56       (Left error) -> putStrLn $ "Failed to insert the todo: " ++ show error
57       (Right result) -> pure ()
58 
59 
60 completeTodo :: Int -> Connection -> IO()
61 completeTodo todoId conn = do
62   completeResult <- try (executeNamed conn "UPDATE todo SET is_done = true WHERE id = :id" [":id" := todoId]) :: IO (Either SomeException ())
63   case completeResult of
64     (Left error) -> putStrLn $ "Failed to update the todo: " ++ show error
65     (Right _) -> do
66       nbUpdatedRows <- changes conn
67       displayUpdateMessage nbUpdatedRows
68 
69 displayUpdateMessage :: Int -> IO()
70 displayUpdateMessage 0 = putStrLn "Failed to find a todo with the supplied id."
71 displayUpdateMessage _ = pure ()

Here are also my stack.yaml file and may package.yaml. I didn't include them here since they are way longer that the other dependencies files and give extra details about how the project must be compiled.

Wrapping up

Some stats to compare each solution:

The full code of the Rust version is 220 lines, but only 164 lines of code when I remove the lines with the closing curly which we don't have in other languages. It's also the app where I have the most detailed and precise error messages. It felt right to write it this way.
The Clojure version is 147 lines long.
The Haskell version is 149 lines long.

So I'd say in terms of code length, they all are pretty much the same, with Rust being a bit more verbose.

I'd like to say I enjoyed writing all these apps. The Haskell one was the most challenging to write: it's the language I know the least and is the most different from what I am use to writing. Their usage of Monad and of IO in type signature was (and still is a bit) obscure to me. I think these signatures can be obvious to someone at ease with Haskell, but as a newcomer, without examples to illustrate how the function actually works, it was hard to understand. I often had to search the Internet for examples to help me write the code. I also struggled a bit with the operators <$> and <*>.

I'm also a bit disappointed by the Clojure version: the argument parser is less complete than the other ones and I was expecting more of it. I also still have issues reading the code at time, mostly when I want to scan the code to find something. Maybe it's just a habit to work on.

I think the Rust one shines: it's expressive, errors must always be handled correctly and I found many examples as well as solid library to implement what I was trying to do. This small experiment made the language more interesting for me. It's definitely the one I'm most exited about although I still don't think I'll use the language much aside from toy project for now: I find it a bit verbose and complex for the web app I am writing.

I'll try to write a small web API in the following weeks to complete my experience (and for fun) and write an complementary blog post.

In July, I finally wrote the follow up article: Small API to manage packages.

Testing a clojure web framework

2020-08-02T00:00:00+02:00

After learning Clojure thanks to the awesome book Clojure for the Brave and True I decided to test some web programing with the language to practice a bit.

Before dwelling on this experience, I'd like to say a few words about the language itself. I heard about the language when I was still completing my masters degree in 2014 or 2015. I didn't gave it much attention back then. Later, I noticed that Robert C. Martin (author of the book Clean Code among other books) talked about it and seemed to enjoy the language. Since I respect his technical opinion, it raised my interest again and I look a bit into it and bought the book Clojure for the Brave and True which then sat on my bookshelf for a couple of years. Until the middle of last year when I decided to seriously look at functional programming and finally went through the book.

This was mind blowing! In addition to the great qualities of the book who made the learning journey really fun, I found the language itself to be really well designed and interesting to learn. I like the notion than almost everything is a function (the example with the simple + function at the beginning of the book really hooked me up), the way it handles "polymorphism", atoms and references… I also had to change perspective and get used to everything being immutable which requires lot of thinking at first but forced me to reconsider many things about my daily programing practice. The fact that the book comes with many exercises after each chapter is a great plus to sharpen the reader's skills. It's a great learning experience and I do encourage you to learn the language. I must confess I still have issues with the syntax (it's a LISP after all with lots of parentheses everywhere) and how to organize my code. But I don't practice much, so I guess it's normal.

Moving on to web development and Luminus. In order to practice and to do something that resembles what I do daily (web development), I decided to write a small website using the language. I looked around for a library/framework to help me in this endeavour and found Luminus which looked very good: the documentation is very detailed and it has a great getting started. It also has a lot of template to create projects with different setup easily (like choose which database you want or to bootstrap the frontend for you). I also dwelled a bit on frontend development with ClojureScript (the version of Clojure designed to run in the browser) and Reagent, a library written in ClojureScript that leverages React to create dynamic interfaces. After some quick tests, I knew I would be able to do what I wanted.

My goal was to create a site to help manage various competitions. In the end, I mostly played with Reagent and coded the home page of the site as well as the detail pages for each competitions. I initially wanted to add a form to add competitions and a search feature but gave up due to lack of time. The frontend was entirely done in Reagent and communicated with the backend thanks to REST. The code is available here if you want to take a look at it.

I liked how the frontend and backend can work together and never require a full server restart. The code, from both the frontend and the backend, is updated via hot updates which makes the developer experience very fluid. That's also very important since the server is very slow to start, without this auto-reload feature, I think the development experience would be very poor. It also means I almost never had to fully reload the page. That was really pleasing.

On the unpleasing side of things: I decided to use a SQL database (as I saw while making the getting started). From what I tested, that's where the framework doesn't shine: I had to write SQL for each query I had to make which doesn't seem very flexible to me. Maybe because I'm too used to the Django ORM by now to revert to raw SQL for every requests. I also had to restart the server each time I edited a query for my changes to be taken into account. That was adding to the pain I felt when writing SQL queries and one of the reason I decided not to take more time on the project: it would require even more queries. I looked for ways to avoid this, but didn't find anything (I may not have looked hard enough) and still thinks the framework should handle this for me. What's strange is other than that, the experience is very fluid and hot reload work perfectly. This made me think that it's also partially why MongoDB is so popular: all you need is to send JSON to the server and all languages have good tools to do this, mostly Clojure with its emphasis on data and using maps [1] everywhere. No need for someone to build and maintain the complex piece of technology that is an ORM.

All in all, I'm satisfied with what I did and intend to continue trying stuff with Clojure. If I do something else, I'll probably use MongoDB to avoid SQL altogether.

[1]	Also known as dict in Python.

Retrospective on my biggest personal project

2020-07-19T00:00:00+02:00

Today I'd like to look back at my longest (and biggest) personal project and what I learned along the way. The project is now called Last Run (but was named Arena of Titans when we started). It's a board game adapted for web usage. It went live a few month ago and is available here. The project is also entirely Open Source under the AGPLv3 license with the code source hosted on gitlab. If you play and have feedback, let me know! We are on social media or you can leave a comment here.

I started the project in 2014 when I was completing my studies in Centrale Marseille, a French engineering school. At the time, we were 4 on the project: the creator of the game, myself and two other developers. This project was accepted as our final project assignment which was a great way to combine passion and usefulness. Now we are three: the creator of the game who does a bit of development but is mostly working on the gameplay, myself as the main developer and a new developer who participates from time to time.

The original version of the game was written in Java and AngularJS. I remember I looked at Apache Wicket and Vaadin to do everything in Java, including the frontend. This idea was influenced by a fellow student (but not teammate) who really liked Vaadin (and maybe still does). Eventually, after some tests, it became clear the project wasn't really fitting into this model (don't ask me exactly why, it was years ago) and I settled on AngularJS (for the best I think). At this time, the frontend did HTTP requests to the API because it was easier this way given what we knew and all players had to play on the same computer because it was easier for us and we didn't really know how to update other browsers even if they were connected to the same API. Since HTTP requests should be stateless, I stored the game state in Redis which is the only original technical decision that remained over the years. It was also the early days of Docker, which looked cool and could allow me to avoid installing Java on my server, so I initially deployed the app with it. It was a bit painful (mostly because I did it at the very end of the project so the examiners could see it on the web) but it was interesting and fun to do.

After graduation, the creator of the game and myself still wanted to work on the game to improve it while the other members of the team didn't and left. I tried to improve the Java version, mostly to add proper multiplayer and to rely on websocket to provide real time, two-way communication with the API. However, I've always been a Python guy and choose Java for the first version of the game only because it was more convenient for other team members. I was also a bit tired of the ES5/AngularJS frontend and wanted to switch to ES6 (we were in 2015 at this time, JS already made its "revolution" with ES6). The fact that ES5/AngularJS was what I was using at work also influenced my decision: I wanted to play with something new and different.

So, I decided to rewrite the thing. I tested few options in the backend:

Go: it felt complicated given what I knew and what I was trying to achieve. Furthermore, I dislike the type system, maybe because I came from a Java and Python background. My main paint point was that I was already using sets in the algorithm and since Go doesn't have sets in the standard library, I needed an extra package. And since Go doesn't support generics, I had to allow any type in my sets which defeats the purpose of a type system in my opinion. That's the equivalent of doing Set<Object> in Java which is strongly discouraged.
NodeJS: it felt very young and was lacking some modern APIs (like Set) at the time. That would have required to either not use them or to somehow transpile the code which I wasn't willing to do. And the future of the project wasn't very clear at the time with the io.js fork.
Python: I was able to do all I wanted and it's a language I always used and loved. I was also using it at work, so it made sense to use it here too. Did I really need to test anything else you may ask? For the sake of testing and experimenting I may answer. I choose (and still use today) the Autobahn library for websocket communication. What I found interesting was that I could use it with asyncio (which landed in the standard library in Python 3.4, the Python version of the time) which seemed like the way to go for async programing. That was a very goo choice, mostly in Python 3.5 when the async and await keywords were introduced and completely made asyncio the way to go for new async code.

In the frontend, I tried several options (VueJS wasn't really a thing at this time, so I didn't tested it):

Angular 2 (now just named Angular): it seemed like the logical choice since the existing app was written in AngularJS. The framework was in Beta at the time. I really didn't like the experience it provided: it felt very complicated and cluttered. I also encounter several problems with the router which didn't invite me to trust the framework. Even after reading a book about it a few months later, after it was officially released, it still felt over-engineered and not that clear to me. So I was glad I discarded it.
Ember: it felt nice but limiting because of how it handles data. I didn't really adhere to its ways of doing things. Still felt like a strong framework.
React: it didn't left much of an impression at the time. I don't think it was that popular back then and it felt like I would lack some structure and need to add many things by myself (which is consistent with the fact it's more a rendering library than a framework).
Aurelia: that's the framework I immediately loved. It felt like an updated and simplified (in a good sense) version of AngularJS. I saw how I could transfer and improve my existing practices of working with AngularJS. I still think it is an under-appreciated framework that deserves to be more known.

So after these tests, I decided to rewrite the project in Python with Autobahn using asyncio and Aurelia in the frontend. I started in July 2015 and I think I completed a first version during the rest of the summer. Of course the project evolved over time:

I added CI to run my tests automatically.
I add many linters (both in the backend and in the frontend). I also added prettier and black to automatically format my code. I check formatting with a pre-commit hook in git and even let PyCharm reformat the code on save.
I switched to pre-commit to manage my pre-commit hooks.
I switched to Aurelia store to manage the application state. I initially relied on a custom service but relying on a more complete solution made sense in the end. See this article to learn more about this process.
I added validation in the API. Initially I always assumed I was given proper data (I guess I was young and unafraid back then). By the way, in Python, Cerberus is a very good library to do that!
I'm stricter in my usage of functions: initially I embraced the flexibility of Python a bit to much and allowed both Card object and tuple (card_name, card_color) (which allowed me to find the proper Card object) to be passed around which made the code more complex and more fragile. I'm stricter now in how I define the interfaces of my functions.
I reduce various subjects of tech debts and simplified many portions of the code thanks to all the things I learned in Python, JS and programming in general over the last 6 years.
I changed a few times of package managers and bundles for the frontend. See this article to learn more.

One very important point I haven't talked about yet is the deploy process. That's another area where I learned much over these years! I had a server even as a student, so I used it even for the earliest versions of the game. I don't remember exactly how I deployed the first version of the app using docker though. I think I just exported the image as a tar.gz and imported it on the server with some kind of custom Bash script. Since it was the early days of docker which wasn't very stable at the time, I switched to standard uwsgi directly on the server and packaging all Python dependencies as RPM packages installed on the system (luckily I didn't have much of those because it takes a lot of time!). Later, when I wanted to switch to a more powerful server, I think I switched back to docker because it made dependency management and deploys easier. At this stage, I was still using custom Bash scripts to build and deploy images. The front was deployed with Rsync. It was a bit weird, not always stable but globally worked. After that, I switched jobs and discovered Ansible as a tool to deploy stuff. Since it way more stable and complete than what I could create by hand, I switched to it a few years back. That's where I am now: a bunch of Ansible playbooks to build and deploy both the frontend and the backend. The backend runs in docker and the frontend is served directly by nginx because it doesn't need anything else. I still have a Redis instance that was deployed once, so it doesn't bother me much.

The last thing I'd like to share is how I handle multiple versions of the game. It's not very useful right now since we don't have many players but it felt like something I had to do correctly from the start because it would be harder to add later on. Since the game can change from one version to another (because we had features), incompatibilities can arise: the frontend can send a request in an older format or the API can require new information the frontend cannot send yet. The result would be a broken game for the player. I could use feature flags to detect which code path to use and have a single instance of the API but I think it would clutter the code more than serving the actual purpose. So I decided that each version of the frontend would talk to a dedicated version of the backend. To do that, I developed a small gateway which reads the version of the API the frontend wants and transfer the traffic to the proper container. It's written in Go because I really wanted to give another try to this language and though this routing gateway would be a very good fit for the language (which I still think it is). When you go on the site, nginx will always serve the latest version of the frontend by default. Once you start a game, the version of the frontend is used in the URL so if you refresh the page, you will get the proper version.

To conclude, I really like the project. It took time to go to where we are now for various reasons: I made mistakes because I was a beginner, I can only work on the project during my spare time, I'm mostly the only developer working on the project and we made some changes in the gameplay that had a huge impact on the structure of the project. Overall, I am pleased and proud of the work accomplished. I learned a lot, was able to try thing and spent countless hours over Python, JS, Bash or Docker problems. This may sound like a loss of time but it was a great way to learn. I still plan to work on this project and don't know where it will be in 6 years from now. If it's still around, I'll try to publish a follow up article!

Feedback after switching to openSUSE Tumbleweed

2020-05-15T00:00:00+02:00

This article is a follow up to Installing openSUSE next to Fedora with BTRFS where I detailed how I switched to openSUSE Tumbleweed. In this article, now that I have been using Tumbleweed for about 2 months and a half, I'll give some feedback on my experience.

The issues I had:

For some reason, I lost an EFI file used by Fedora to boot which prevented me to run my Fedora installation. I was able to restore it by copying another EFI file (mmx.efi) into the proper location.
Unlocking the LUCKS drive in Grub is slow. Although I find it's a bit faster lately (and it's not an issue with Tumbleweed per say).
Docker sometimes fails to pull images. It only happens in script, running docker pull SOME_IMAGE always runs correctly.

Unlike in Fedora, /tmp is not cleaned automatically after a reboot. You have to enable this manually by putting the content below in /etc/tmpfiles.d/tmp.conf (see this thread for the solution and the reasoning behind it):

#  This file is part of systemd.
#
#  systemd is free software; you can redistribute it and/or modify it
#  under the terms of the GNU Lesser General Public License as published by
#  the Free Software Foundation; either version 2.1 of the License, or
#  (at your option) any later version.

# See tmpfiles.d(5) for details

# Clear tmp directories separately, to make them easier to override
# SUSE policy: we don't clean those directories
D! /tmp 1777 root root -
q /var/tmp 1777 root root -

Updating the kernel to a new minor version (eg from 4.5 to 4.6) can break the Nvidia drivers and thus your display. The patched driver comes relatively fast but it was a bad surprise when it happened to me! I hope the process will be smother in the future. It was also the occasion to experiment booting from a read-only BTRFS snapshot. And it worked well!

Despite these issues (for which I have workarounds anyway), I am very pleased with my experience. The update process works well (with the exception of Nvidia drivers as pointed above) and the system is stable. So I decided to switch all my computers to it (I switched to a rolling release to avoid Fedora updates after all, didn't I?).

I must also say that YAST (which acts as a configuration panel for you computer from firewall to installing packages) is well done and a pleasure to use. No need to search/install different tools, just use YAST!

I also find the use of openSUSE of BTRFS snapshots to be really cool. I haven't used them much since the system is stable and I haven't encountered issues with updates (except once with Nvidia). But it's still a nice thing. I'll just note that while installing openSUSE to another computer, I made a big configuration mistake that locked me out of the system. Thanks to the snapshots and the rollback mechanism, it wasn't such a big deal (because yes, /etc will be in the snapshot too). Without it, I might have needed to reinstall everything. So I don't need them often, but I'm really glad they are here when I do.

This post wouldn't be complete without some observation on KDE. As a long time Gnome user, I also decided to switch to KDE to see how it goes (and while your changing, why not change more?). I am pleased with the change and was able to adapt to KDE very quickly (despite many years of using Gnome). I do appreciate the fact that many things are integrated by default (like the clipboard manager or media player integration) whereas you need extension in Gnome to do this. I also really like the fact that the command that ask for the root password is mentioned on the popup that ask for it. I think it is a big plus for security.

I had some issues though, here is the list and how I solved them:

I cannot configure my gmail account to use it easily with KMail. From what I read, I have to enable IMAP support in gmail. In Gnome this is supported by default (calendar works fine though). Since I only have my professional mailbox in it, I can just keep gmail opened in a pined tab. So not a big deal.
Since I use the same user on both Fedora and openSUSE, when KDE launched it changed some configuration and now the close, maximise and minimise icons looks a bit funny on Gnome.
I use the bépo keyboard disposition (which was made specifically for French). It was really easy to configure this keyboard disposition in the session but harder to enable it on the login screen (although it may come from the fact that openSUSE doesn't support this disposition during install unlike Fedora). Luckily, this post on the ArchLinux forum had the solution: update /etc/X11/xorg.conf.d/00-keyboard.conf with the content below.
```
Section "InputClass"
    Identifier         "Keyboard Layout"
    MatchIsKeyboard    "yes"
    MatchDevicePath    "/dev/input/event*"
    Option             "XkbLayout"  "fr"
    Option             "XkbVariant" "bepo_latin9"
    Option             "XkbOptions" "terminate:ctrl_alt_bksp"
EndSection
```
I had to create a script in .config/autostart-scripts/ssh-add.sh with the content below to correctly pre-load my SSH keys, something that worked by default on Gnome. The script is based on this article from the ArchLinux wiki.
```
#!/usr/bin/env bash

for key in $(ls -d ~/.ssh/* | grep -v pub | grep -v authorized_keys | grep -v config | grep -v known_hosts | grep -v seahorse); do
    ssh-add -q "${key}"
done
```

I also find the combo KDE + openSUSE to need less RAM that my Fedora + Gnome.

So, to conclude, I am very pleased with the change and don't regret doing it.

Installing openSUSE next to Fedora with BTRFS

2020-02-23T00:00:00+01:00

Update: My feedback article is now available.

I wanted to install openSUSE Tumbleweed (the rolling release version of openSUSE) on one of my computers to see how it looked outside a VM (and thus to try to use it daily). I am thinking about switching to this distribution to avoid major updates of Fedora. They happen every 6 months and I have multiple machines to update, so I find it cumbersome to update them all (and I like to test new stuff too ^^).

Why openSUSE? Because it looks stable, well tested, it provides a graphical installer (I already installed Arch and Gentoo in the past and wasn't enthusiastic about doing this again) and has some nice defaut with BTRFS (snapshots and booting from snapshots without having to configure it manually). I also know a contributor and a long time user of openSUSE and Tumbleweed who's very happy about the system.

In this article, I'll explain how I installed it next to my Fedora (which I don't want to loose it until I commit to making the switch). Some things are specific to my setup, others are more generic and should be reusable (more or less easily). If you have any question or remark, please leave a comment. I'll assume you have some knowledge of BTRFS.

Starting point

I had fedora installed with a BTRFS top level volume and 3 child volumes root for /, var for /var and home for /home. Since I use docker with the BTRFS driver I also had many subvolumes of /var for docker.

I also installed Tumbleweed in a VM to see how it behaves. I created another VM with Fedora installed just like on my computer so I could try installing Tumbleweed next to it without breaking my current setup.

Preparing Fedora

I removed the docker containers and images as well as all docker related subvolumes that remained. I don't know whether this could have an impact and didn't want to risk it (nor did I wish to migrate them).
The two most useful commands you can use at anytime to check something are:
- btrfs subvolume list PATH to list all subvolumes in the supplied filesystem.
- btrfs subvolume show PATH to see which subvolume is mounted under the supplied path.
Disable SELinux: it's not used in openSUSE so I think some files will be mislabeled which may prevent Fedora to work properly (or maybe just prevent me to access some files, I don't know and I don't want to test). Let's simply as much as possible and remove it from the equation.
Since my subvolumes are named var, root and home, the Tumbleweed installer will mount them under /var, /root and /home. I didn't find a way to prevent this. For /home it's the behavior I want since I want to keep my data. For the other two, it's not. You cannot rename subvolumes directly but you can rely on snapshots to achieve it. To do so, I (as root):
1. Mounted the top level BTRFS volume (which is not accessible by default) with: mount -t btrfs -o subvolid=5 /dev/vda3 /mnt/toplevel/ (most of my commands are copied from when I tested in a VM, hence the vda, adapt this part to your setup).
2. Created a snapshot for the root subvolume: btrfs subvolume snapshot /mnt/toplevel/root/ /mnt/toplevel/fedoraroot/
3. Emptied /mnt/toplevel/fedoraroot/var to remove the directory with rmdir /mnt/toplevel/fedoraroot/var
4. Created another snapshot for var (I decided to make it a subvolume of fedoraroot because I think it makes sense to have one top volume for Fedora): btrfs subvolume snapshot /mnt/toplevel/var/ /mnt/toplevel/fedoraroot/
5. Migrated the nested subvolumes for /var:
```
[root@baley toplevel]# rmdir /mnt/toplevel/fedoraroot/var/lib/machines/
[root@baley toplevel]# btrfs subvolume snapshot /mnt/toplevel/var/lib/machines/ /mnt/toplevel/fedoraroot/var/lib/
[root@baley toplevel]# rmdir /mnt/toplevel/fedoraroot/var/lib/portables/
[root@baley toplevel]# btrfs subvolume snapshot /mnt/toplevel/var/lib/portables/ /mnt/toplevel/fedoraroot/var/lib/
```
6. Identified each subvolume so I could know which ones where mounted as my main filesystem:
```
[root@localhost ~]# touch /mnt/toplevel/root/stdroot
[root@localhost ~]# touch /mnt/toplevel/fedoraroot/fedoraroot
[root@baley toplevel]# touch fedoraroot/var/fedoravar
[root@baley toplevel]# touch ./var/stdvar
```
7. Updated fstab in the snapshot (that's in fedoraroot) since that what we want to use from now on. To do so, I replaced subvol=root by subvol=fedoraroot```and ``subvol=var by subvol=fedoraroot/var.
8. Rebooted.
9. Edited the grub line from the menu before booting from it. I updated the subvol parameter of the kernel to be subvol=fedoraroot. This way grub mounted the proper subvolume during boot.
10. Checked that everything was correct:
```
[root@localhost ~]# btrfs subvolume show /
fedoraroot
        Name:                   fedoraroot
        UUID:                   1fc8ffa2-76f5-a343-aae9-4b499073d805
        Parent UUID:            5effda61-179e-9b48-900f-b7ad85d5f9d9
        Received UUID:          -
        Creation time:          2020-02-22 16:14:19 +0100
        Subvolume ID:           268
        Generation:             4554
        Gen at creation:        4447
        Parent ID:              5
        Top level ID:           5
        Flags:                  -
        Snapshot(s):
[root@localhost ~]# ls /fedoraroot
/fedoraroot
```
11. Remounted the top level volume.
12. Deleted the nested subvolumes: btrfs subvolume delete /mnt/toplevel/root/var/lib/machines/ (same for portables).
13. Deleted root and var:
```
btrfs subvolume delete /mnt/toplevel/root/
btrfs subvolume delete /mnt/toplevel/var/
```
14. Updated grub: grub2-mkconfig -o /boot/grub2/grub.cfg # or /boot/efi/EFI/fedora/grub.cfg if you use EFI
15. Checked the generated grub configuration:
```
[root@localhost ~]# grep -R subvol /boot/grub2/grub.cfg  # The subvolume parameter is correct.
set default_kernelopts="root=UUID=ce254a08-22e0-481e-b027-498aa059cc1a ro rootflags=subvol=fedoraroot resume=UUID=163891ab-ac20-4e58-8731-306810f99c9c rhgb quiet "
```
16. Rebooted. All should still be working.

Installing Tumbleweed

Just do the normal installation process until you reach the disk setup. Here you'll have to choose Expert partition and Start with existing partitions. Then, on the disk that contains you BTRFS volume:

Mount the swap
Mount the EFI partition under /boot/efi (if you use EFI).
Mount the main BTRFS volume / and be sure to skip the formatting of the volume. /boot must be under / in the BTRFS volume even if you use luks. See below for why.
Check installation summary: should not remove anything but should create a lot of new subvolume. None should conflict with fedora's.

That should be it. Inspect in the summary the operations done. You should see that the installer:

Will create all the subvolumes it needs.
Won't delete anything.
Will mount the fedora subvolumes. Not a big deal, we will remove that from the fstab once the installation is done.

You can launch the installation.

Finishing the setup of Tumbleweed

If you use luks, you will have to enter you luks passphrase in Grub with a US keyboard. You will then have to enter you passphrase normally as part of the boot process.

By default Tumbleweed will create a subvolume named @ and create its other subvolumes as subvolumes of it. Here however, it didn't (I don't know why). Since I still want a main subvolume for each system (having home as a direct subvolume of the top level volume sounds good to me since it is independent of any other system). So, it's time to move subvolumes again. I won't detail much this time, I think you know the drill (do this from fedora, the directories are in use in Tumbleweed):

mount -t btrfs -o subvolid=5 /dev/vda3 /mnt/toplevel/
cd /mnt/toplevel/
btrfs subvolume list .

# Repeat for each subvolume.
rmdir /mnt/toplevel/@/var/
btrfs subvolume snapshot /mnt/toplevel/var /mnt/toplevel/@

# Check. Don't remove subvolume while in use, the deletion will come later.
btrfs subvolume list /mnt/toplevel
btrfs subvolume list .

Let's edit the fstab. We are just appending @/ to each subvol arguments like this: subvol=@/var.

We also need to update /boot/grub2/x86_64-efi/load.cfg so grub mounts the correct subvolume during the boot process:

set btrfs_relative_path='y'
cryptomount -u bf63369674824969a7726fda0cb46537
btrfs-mount-subvol ($root) /boot/grub2/x86_64-efi @/boot/grub2/x86_64-efi

Note

I didn't need this step in my VM and given the content of the file, I think it is specific to luks.

We can now reboot. Everything should go well. Boot on the other system if not.

We can now delete the old subvolumes from the installation:

mount -t btrfs -o subvolid=5 /dev/vda3 /mnt/toplevel/
cd /mnt/toplevel/
# Repeat for each subvolume.
btrfs subvolume delete ./var

We can also enable snapper now to have snapshot. It's done automatically during a normal installation but not here (because we did weird things I guess). We can do this with snapper -c root create-config /. And we are done!

Warning

Fedora uses subvol in grub.cfg but not Tumbleweed. Tumbleweed changes the default subvolume of the top level volume. It's not a problem with this setup but if you want to install two systems that do this, you will have to make at least one explicitly use subvol everywhere.

Wrapping up

It required a lot of preparation and tests but I'm glad I made it. I find Tumbleweed fast (faster than fedora at boot and when installing package) and reliable (from what I used until now). I'll need to do more testing to confirm that (the system is very fresh after all). I also learned a lot about BTRFS, subvolumes and snapshots along the way. I still have some issues though:

The nextcloud client ask me to reconnect each time I launch it. It may come from a configuration shared with Fedora. I'll fix this later once I know which system I want to keep.
The grub menu to choose the kernel (or the snapshot) is sometimes not displayed.
Grub takes some time to start once the key is entered.
If I fail to enter my passphrase for grub of the first try, it fails and I have to do a hard reboot.
I decided to switch from Gnome to KDE and I think I hit a bug with the online accounts that prevent me to setup my gmail account. I'll have to dig into this later (I'll try to update this post if I find the solution). I also spent a lot of time to configure KMail (which has a lot of options by the way).

Bonus

Enter luks passphrase only once

If you use luks, you have to enter your luks passphrase twice: once to unlock /boot so grub can start the system and then so the system can access the disk. Sadly, they can't communicate (yet?).

You could put /boot on an unencrypted filesystem (that's what fedora does), but according to this thread you won't be able to boot from a BTRFS snapshot (which is one cool thing Tumbleweed enables by default).

You can also fellow these steps so you'll only have to enter the passphrase for grub. Check also this link to update the initramfs in Tumbleweed (don't forget to launch dracut --force). For reference, my /etc/dracut.conf contains:

# PUT YOUR CONFIG IN separate files
# in /etc/dracut.conf.d named "<name>.conf"
# SEE man dracut.conf(5) for options
install_items+="/etc/luks-keys/root.key"

Note

If you need to add many files, separate them with spaces like this: install_items+="/etc/luks-keys/root.key /etc/luks-keys/swap.key"

Tip

Don't add key-slot=1 immediately, if you did a mistake you will be locked out of the system because luks will try to match the key against this slot. Don't forget to adapt the slot if needed. You may also choose not to add it since I found it doesn't really change the boot time anyway.

Tumbleweed default install

For reference:

localhost:~ # btrfs subvolume list /
ID 256 gen 32 top level 5 path @
ID 258 gen 4192 top level 256 path @/var
ID 259 gen 4125 top level 256 path @/usr/local
ID 260 gen 4192 top level 256 path @/tmp
ID 261 gen 3045 top level 256 path @/srv
ID 262 gen 4166 top level 256 path @/root
ID 263 gen 3620 top level 256 path @/opt
ID 264 gen 4192 top level 256 path @/home
ID 265 gen 26 top level 256 path @/boot/grub2/x86_64-efi
ID 266 gen 3550 top level 256 path @/boot/grub2/i386-pc
ID 267 gen 4118 top level 256 path @/.snapshots
ID 268 gen 4191 top level 267 path @/.snapshots/1/snapshot
ID 274 gen 197 top level 267 path @/.snapshots/2/snapshot
ID 275 gen 262 top level 267 path @/.snapshots/3/snapshot
ID 278 gen 485 top level 267 path @/.snapshots/4/snapshot
ID 282 gen 1614 top level 267 path @/.snapshots/5/snapshot
ID 283 gen 2100 top level 267 path @/.snapshots/6/snapshot
ID 290 gen 3024 top level 267 path @/.snapshots/11/snapshot
ID 291 gen 3066 top level 267 path @/.snapshots/12/snapshot
ID 292 gen 3233 top level 267 path @/.snapshots/13/snapshot
ID 295 gen 3551 top level 267 path @/.snapshots/14/snapshot
ID 296 gen 3593 top level 267 path @/.snapshots/15/snapshot
ID 297 gen 3613 top level 267 path @/.snapshots/16/snapshot
ID 301 gen 3631 top level 267 path @/.snapshots/17/snapshot
ID 305 gen 4005 top level 267 path @/.snapshots/18/snapshot
ID 306 gen 4051 top level 267 path @/.snapshots/19/snapshot
ID 307 gen 4113 top level 267 path @/.snapshots/20/snapshot

localhost:/mnt/toplevel # cat /etc/fstab
UUID=e5a3ef21-d865-4bb6-bd11-6056ff4a60b1  /                       btrfs  defaults                      0  0
UUID=e5a3ef21-d865-4bb6-bd11-6056ff4a60b1  /var                    btrfs  subvol=/@/var                 0  0
UUID=e5a3ef21-d865-4bb6-bd11-6056ff4a60b1  /usr/local              btrfs  subvol=/@/usr/local           0  0
UUID=e5a3ef21-d865-4bb6-bd11-6056ff4a60b1  /tmp                    btrfs  subvol=/@/tmp                 0  0
UUID=e5a3ef21-d865-4bb6-bd11-6056ff4a60b1  /srv                    btrfs  subvol=/@/srv                 0  0
UUID=e5a3ef21-d865-4bb6-bd11-6056ff4a60b1  /root                   btrfs  subvol=/@/root                0  0
UUID=e5a3ef21-d865-4bb6-bd11-6056ff4a60b1  /opt                    btrfs  subvol=/@/opt                 0  0
UUID=e5a3ef21-d865-4bb6-bd11-6056ff4a60b1  /home                   btrfs  subvol=/@/home                0  0
UUID=e5a3ef21-d865-4bb6-bd11-6056ff4a60b1  /boot/grub2/x86_64-efi  btrfs  subvol=/@/boot/grub2/x86_64-efi  0  0
UUID=e5a3ef21-d865-4bb6-bd11-6056ff4a60b1  /boot/grub2/i386-pc     btrfs  subvol=/@/boot/grub2/i386-pc  0  0
UUID=e5a3ef21-d865-4bb6-bd11-6056ff4a60b1  /.snapshots             btrfs  subvol=/@/.snapshots          0  0
UUID=6f2fce23-6460-4d69-9e69-a5b6b5e4456c  swap                    swap   defaults                      0  0

Mon passage à LineageOS

2017-03-29T00:00:00+02:00

Tout d'abord, je présente un projet intéressant : oandbackup que j'ai découvert via cet article. oandbanck vous permet de sauvegarder les APK installés sur votre téléphone pour pouvoir les réinstaller une fois la mise à jour effectuée. Malheureusement, suite à un problème lors de la mise à jour, j'ai dû formater ma carte SD, du coup, je n'ai pu tester que la sauvegarde et pas la restauration. Mais d'après ce que j'ai lu, ça fonctionne très bien.

Concernant l'installation à proprement parler : j'avais déjà tenté une installation début février avec une nightly pour mon galaxy s2. Ça c'était mal passé : l'installation n'arrivait pas à se terminer. Après plusieurs tentatives infructueuses, les builds de cyanogenmod n'étant plus disponibles, j'ai fini par installer une vieille build de replicant pour pouvoir passer des appels et recevoir des SMS. Comme le projet lineageos a pas mal bougé (et que la build de replicant était vraiment vieille), j'ai retenté le week-end dernier une installation. J'ai eu quelques soucis mais j'ai réussi à les contourner. Voici ce que j'ai fait :

Télécharger une image récente : https://download.lineageos.org/
Télécharger l'utilitaire SU : https://download.lineageos.org/extras
Copier les fichiers sur la carte SD
Installer TWRP (le mode recovery) : c'est à partir de là que les choses ont commencés à ce gâter. J'ai tenté la commande issue de la documentation:
```
heimdall flash --KERNEL twrp-3.1.0-0-i9100.img --no-reboot
```
Malheureusement, impossible de démarrer sous TWRP : le téléphone démarrait sous l''ancien recovery. J'ai bien tenté heimdall flash --KERNEL twrp-3.1.0-0-i9100.img --no-reboot (ce que je faisais avec mes anciennes recovery) mais là, impossible de démarrer. D'après ce que j'ai compris, cela vient du fait que TWRP est plus qu'un simple mode recovery, il a besoin d'un noyau pour démarrer. La solution, c'est d'utiliser le noyau contenu dans l'image LineageOS pour pouvoir démarrer en mode recovery. Pour cela :
1. Dézipper boot.img de l'image.
2. Lancer avec le téléphone en mode téléchargement :
```
heimdall flash --KERNEL boot.img --RECOVERY twrp-3.1.0-0-i9100.img
```
Normalement, maintenant, le téléphone peut démarrer en mode recovery.
Effacer les "caches" dalvik, data, system, et cache.
Lancer l'installation du zip. Dans mon cas, l'installation se bloquait aux trois quart environ. En regardant les messages, j'ai vu : Failed to mount '/system'. J'ai testé pas mal de choses (revider les caches, changer le système de fichier avec parted, …) mais rien n'y a fait. Heureusement, j'ai fini par trouver ce thread reddit qui donne la solution : réparer le fichier PIT du téléphone. Pour cela, télécharger le PIT "qui va bien" (ou via le lien original). Ensuite, lancer en mode téléchargement (où boot.img est le noyau de LineageOS dézipper précédemment):
```
heimdall flash --repartition --pit I9100_1.5GB-System_6GB-Data_512MB-Preload_by-the.gangster.pit --KERNEL boot.img --RECOVERY twrp-3.1.0-0-i9100.img
```
À ce stade, l'installation du zip devrait fonctionner (j'ai revidé les caches avant on ne sait jamais).
Installer su
Redémarrer
Normalement tout va bien

Malheureusement, je ne sais plus à quel moment j'ai dû effacer la carte SD (je n'ai pas pris de notes pensant pouvoir écrire ce billet plus tôt). Mais de mémoire, c'était évident donc j'espère que pour vous aussi. Et si vous rencontrez un problème, vous pouvez laisser un commentaire !

Angular2 and SVG

2017-02-21T00:00:00+01:00

Note

I use the Aurelia framework, a competitor of Angular2. I wrote several articles about Aurelia. I am not an expert with Angular2. If you spot a mistake, please leave a comment.

In an interview about a year old, Rob Eisenberg, the creator of the Aurelia framework, said:

Over a year ago the Angular 2 team introduced their symbolic binding syntax. While that was technically standards compliant HTML, it was pointed out by the community that it was not compliant SVG (I have not confirmed that myself). Although members of the community pointed this out, the Angular 2 team made no changes to their design.

Since I recently completed a book about Angular2 and that I heavily use SVG in my applications, I wanted to test it myself. So I created an app with the cli (you can install it with npm install -g angular-cli@1.0.0-beta.22-1). Nothing fancy, just ng new test-svg. I then created a small SVG with Inkscape (it just contains a rectangle) and copied it into the template of the application.

I ran ng serve to build the application, opened it in a browser and BOOM, first error:

zone.js:388Unhandled Promise rejection: Template parse errors:
':sodipodi:namedview' is not a known element:

From what I know, Angular2 has its own HTML parser (mostly to parse camel cased syntax like ngIf which is not HTML compliant) and it fails if it encounters an HTML tag or attribute it doesn't know. While it's nice to help you spot typos in the name of your component, if a piece of HTML or SVG has a non standard tag or attribute, it will crash. Here it is not a big deal, my SVG is small, I can get rid of <sodipodi:namedview /> and <metadata />. But in one of my application, I need to display user uploaded SVGs. Once uploaded, I add AngularJS tags so I can display only certain elements of it depending on actions of the user. These SVGs will contain non standard tags like the Inkscape ones. How can I get rid of all of them so that Angular2 is happy? Whitelist? But what should I put in it? Blacklist? Same question. There are many SVG software out there, each may have its quirks.

This made me wonder: what if I use a brand new HTML 5.1 tag? Will it crash? I tried the code below, and it worked. I guess the parser is already 5.1 compliant. But to support 5.2 you will probably need to update Angular.

<details> // Start Of A New Accordion Element
    <summary> TITLE OF ACCORDION ELEMENT </summary>
    // Anything Here Will Be Displayed After Accordion Is Toggled To Open
    <p>
        Cras dictum. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Aenean lacinia mauris vel est.
    </p>
</details>

Now that we have a working SVG, it is time to add Angular2 markup. Let's start simple and add an ngIf attribute to show/hide the SVG based on the value of a variable:

<svg *ngIf="showSvg"

Let's add a button to toggle the value of the SVG:

<button (click)="toggleSvg()">Toggle SVG</button>

And the toggleSvg function:

toggleSvg() {
    this.showSvg = !this.showSvg;
}

And this works. The SVG is correctly displayed/hidden when I press the button.

Next step: hide the SVG when I click on the rectangle. Let's add the proper attribute:

<rect (click)="toggleSvg()" … />

If I click on the rectangle, the SVG is hidden as expected.

Next step: display multiple rectangles. Let's add a rectTops property to the component. It contains the y value for SVG rectangles. We will loop over it to display a rectangle for each value (and in a moment, we will try to bind the value to the y attribute of our rectangles).

rectTops = [30, 50, 70, 90];

<rect *ngFor="let top of rectTops"
   (click)="hideSvg()" … />

If we inspect the DOM, we see all the rectangles in it. Now, let's use the value:

<rect *ngFor="let top of rectTops"
   (click)="hideSvg()"
   [y]="top"
   … />

And it fails:

Unhandled Promise rejection: Template parse errors:
Can't bind to 'y' since it isn't a known property of ':svg:rect'. ("

You may say, no problem, let's use the mustache notation instead:

<rect *ngFor="let top of rectTops"
   (click)="hideSvg()"
   y="{{ top }}"
   … />

No luck, it crashes too with the same error. And bind-y="top"? No luck either, still the same error.

It appears that the correct way to do this is:

<rect *ngFor="let top of rectTops"
   (click)="hideSvg()"
   [attr.y]="top"
   … />

Thanks NexusVI.

History

2017-03-06: Give the solution of how to use binding with SVG attributes. Thanks NexusVI.

Rédiger ses rapports avec rst et sphinx

2014-08-13T00:00:00+02:00

Comme je l'ai déjà évoqué ici et là, j'adore les langages à balisage léger. Du coup, j'essaie de les utiliser partout où je peux. Mais de là à rédiger un rapport avec table des matières, pages de garde et glossaire, il y a un pas. Surtout face à la puissance de LaTeX.

J'avais déjà évoqué org-mode ici et pourquoi j'envisageais de l'utiliser en lieu et place de LaTeX, à savoir :

Bonne intégration avec Emacs
Syntaxe légère
Possibilité d'export en LaTeX
Possibilité d'insérer du code LaTeX

Mais comme je n'ai pas trouvé de bon support pour org-mode dans Pelican, je m'en suis un peu détourné (je l'utilise toujours pour mes notes) au profit le Restructured Text. Comme ce langage a été conçu pour remplacer LaTeX lors pour la génération HTML de la documentation de python, il est particulièrement puissant. J'ai donc décidé de l'utiliser pour rédiger mon rapport de stage.

Je vais vous présenter tout d'abord Restructured Text (rst) puis sphinx (qui est utilisé pour générer la documentation à partir de fichiers rst) et pourquoi je conseille son utilisation pour un rapport plutôt que juste rst.

Restructured Text

Présentation

La syntaxe est simple. Un bloc de texte constitue un paragraphe. On sépare les paragraphes avec un saut de ligne. On peut écrire en italique et en gras :

*italique* et en **gras**

On peut faire des listes numérotées ou non (attention, les tirets et les dièses doivent être correctement aligné et les sous listes doivent être séparées de la liste par un saut de ligne) :

- item 1
- item 2

  #. Sous-liste numérotée
  #. Un deuxième élément de la sous-liste numérotée

On peut inclure des images :

.. image:: /images/diagramme-fast-LaTeX.png
           :alt: Un diagramme fast réalisé en LaTeX
           :width: 150%

du code :

.. code:: python

          print('Hello World')

Il est tout à fait possible de découper son fichier en plusieurs fichiers plus petits, puis de les inclure avec :

.. include:: fichier.rst

On peut également insérer des fichiers LaTeX avec la directive :

.. raw:: latex
         :file: fast.tex

La syntaxe complète est disponible en ligne. Elle peut paraître déroutante au début, mais on s'y fait et dans l'ensemble, je la trouve très bien faite (de même que la documentation d'ailleurs).

On peut ensuite exporter son fichier en HTML ou LaTeX avec respectivement rst2html et rst2latex.

Rédiger son rapport

Rien de bien fantastique, on entre son texte en respectant la syntaxe, on insère la table des matière avec .. contents:: et on exporte le tout avec rst2latex. On compile ensuite ce fichier avec latexmk. On obtient un fichier Pdf tout ce qu'il y a de plus joli (normal me direz-vous, c'est LaTeX qui l'a fait).

Mais cela ne résout pas tout, comme :

Comment fait-on une page de garde ?
Comment utilise-t-on une autre police ?
Comment insère-t-on un glossaire ?

La réponse aux deux premières questions tient en un mot : template ! En effet, rst2latex dispose d'un argument --template au quel on peut passer un fichier contenant du code LaTeX et des variables rst pour personnaliser le fichier pdf.

Le fichier template de base s'appelle default.tex et se trouve ici : /usr/lib/python3.3/site-packages/docutils/writers/latex2e/default.tex (sur mon PC du moins). Il est assez basique :

$head_prefix% generated by Docutils <http://docutils.sourceforge.net/>
\usepackage{fixltx2e} % LaTeX patches, \textsubscript
\usepackage{cmap} % fix search and cut-and-paste in Acrobat
$requirements
%%% Custom LaTeX preamble
$latex_preamble
%%% User specified packages and stylesheets
$stylesheet
%%% Fallback definitions for Docutils-specific commands
$fallbacks$pdfsetup
$titledata
%%% Body
\begin{document}
$body_pre_docinfo$docinfo$dedication$abstract$body
\end{document}

Il n'y plus qu'à le personnaliser avec du code LaTeX pour qu'il réponde à nos besoins :

$head_prefix% generated by Docutils <http://docutils.sourceforge.net/>
\usepackage{fixltx2e} % LaTeX patches, \textsubscript
\usepackage{cmap} % fix search and cut-and-paste in Acrobat
\usepackage[raccourcis]{fast-diagram}
\usepackage[french]{babel}
\usepackage{titlesec}
\usepackage[a4paper,left=2cm,right=2cm,top=2cm,bottom=2cm]{geometry}
$requirements
%%% Custom LaTeX preamble
$latex_preamble
%%% User specified packages and stylesheets
$stylesheet
%%% Fallback definitions for Docutils-specific commands
$fallbacks$pdfsetup
$titledata
%%% Custom font
\usepackage{libertine}
%%% Set numeration
\setcounter{secnumdepth}{3}
%%% Body
\begin{document}
$body_pre_docinfo$docinfo$dedication$abstract$body
\end{document}

Je précise que l'ordre avec lequel vous insérer votre code et les variables est important. Si on met la ligne \usepackage{libertine} (qui change la police) juste après les autres usepackage le choix de ma police sera écrasée par celle de Rst.

Je propose un exemple plus complet en téléchargement (avec notamment une page de garde personnalisée).

On peut également utiliser les options --document-class et --document-options pour personnaliser le document. Il existe bien d'autres options, je vous laisse regarder la sortie de rst2latex -h pour la liste complète.

On générera le fichier .tex avec :

rst2latex
rapport.rst --template=template.tex --documentclass=report --documentoptions=12pt

Et pour le glossaire ? Ce n'est pas possible, faute de syntaxe approprié, directement avec rst. Ça viendra peut être un jour, c'est sur la todo list des dévoleppeurs. C'est là que sphinx entre en jeu.

Sphinx

Présentation

sphinx est un générateur de documentation pour python. Il utilise la syntaxe rst et peut produire des documents HTML, pdf, des pages man, etc. Il propose également des extensions à la syntaxe de base comme term et glossary pour un glossaire et quelques divergences. Par exemple, la table des matières ne se génère plus avec .. contents:: mais avec .. toctree:: et les inclusions de fichier se font avec .. raw::. Typiquement, on utilise un Makefile pour automatiser la génération, Makefile que sphinx est capable de créer tout seul.

Mais rassurez-vous, dans l'ensemble tout fonctionne quasiment comme avec rst. Lorsque je suis passé de rst brut à sphinx, mon seul problème a été l'utilisation des mes entêtes LaTeX personnalisées.

Rédiger son rapport

Il faut tout d'abord initialiser sphinx, avec sphinx-quickstart. Le programme va alors vous poser plusieurs questions pour générer une configuration de base.

Le rapport en lui même se rédige comme sous rst avec les mêmes possibilités d'inclusion de fichiers. Attention toute fois, l'inclusion est relative au Makefile alors qu'aupapravant, elle était relative au fichier d'inclusion.

Lors de mon passage à sphinx, peu importe l'endroit où j'insérais la directive .. toctree:: la table des matières se retrouvait en début de fichier alors que je la voulais après l'introduction et le résumé. Qu'à cela ne tienne, la directive .. raw:: m'a permit d'insérer la commande LaTeX \tableofcontents où je voulais.

.. raw:: latex

         \tableofcontents

Et pour le glossaire alors ? Rien de plus simple :

J'ulitise le :term:`CMS` :term:`Drupal`

.. glossary::

   CMS
     Acronyme de *Content Management System*, soit système de gestion de
     contenu.

   Drupal
     Un des :term:`CMS` les plus connus et réputé. Il est utilisé par de
     nombreuses entreprises et institutions à travers le monde.

Le seul point qui m'a posé problème c'est la configuration. Elle est quasi intégralement géré pour l'export LaTeX par le dictionnaire latex_elements. Par exemple, pour moi :

preamble = r'''\usepackage{fixltx2e} % LaTeX patches, \textsubscript
\usepackage{cmap} % fix search and cut-and-paste in Acrobat
\usepackage[raccourcis]{fast-diagram}
\usepackage{titlesec}
\usepackage[a4paper,left=2cm,right=2cm,top=2cm,bottom=2cm]{geometry}
%%% Redifined titleformat
\setlength{\parindent}{0cm}
\setlength{\parskip}{1ex plus 0.5ex minus 0.2ex}
\newcommand{\hsp}{\hspace{20pt}}
\newcommand{\HRule}{\rule{\linewidth}{0.5mm}}
\titleformat{\chapter}[hang]{\Huge\bfseries\sffamily}{\thechapter\hsp}{0pt}{\Huge\bfseries\sffamily}
%%% Custom font
\usepackage{libertine}
%%% Set numeration
\setcounter{secnumdepth}{3}
'''
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
'papersize': 'a4paper',

# The font size ('10pt', '11pt' or '12pt').
'pointsize': '12pt',

# Babel for french
'babel': '\\usepackage[french]{babel}',

# Additional stuff for the LaTeX preamble.
'preamble': preamble,

# No default title
'maketitle': '',

# No default toc
'tableofcontents': '',
}

La classe du document se spécifie dans la variable latex_documents :

latex_documents = [
  ('rapport', 'Rapport.tex', 'Rapport de stage 2A',
  'Julien Enselme', 'manual'),
]

Les classes habituelles de LaTeX ne sont pas compatibles avec sphinx. Il faut soit utiliser celles par défaut (manual pour un rapport ou how-to pour un article) soit les personnaliser.

Je pense qu'à partir de cet exemple, vous pourrez subvenir à vos besoins facilement. Sinon, vous pouvez toujours poster un commentaire.

Vous trouverez dans la documentation complète toutes des options que je n'ai pas pu vous présenter ici.

Je vous propose également un un fichier de configuration complet

Conclusion

J'espère vous avoir convaincu d'utiliser la puissance et la légèreté de rst et sphinx pour rédiger vos rapports, avec un peu de LaTeX brut par endroit (faute de mieux) en lieu et place des WYSIWYG.

Même si abandonner LaTeX peut faire un peu peur et que la configuration de sphinx est un peu ardue sans exemple complet, je ne regrette pas mon choix et suis bien content d'utiliser rst (même si je dois reconnaître qu'il est dommage que sphinx ne puisse utiliser les classes de base de LaTeX) !

Comment supprimer toutes les tables mysql qui contiennent un motif

2014-07-30T00:00:00+02:00

Récemment, j'ai eu besoin de faire du ménage dans les tables d'une base de données. Toutes les tables à supprimer commençaient par le même motif. Malheureusement, mysql ne permet pas d'utiliser le jocker % dans une requête DROP.

Heureusement la solution est simple. Il suffit de lister toutes les tables ayant ce motif grâce à la requête SHOW TABLES LIKE 'motif%'. Reste à boucler sur ces tables pour les supprimer. D'où le code suivant :

motif=del_
for table in $(mysql database -NBe "SHOW TABLES LIKE '$motif%'"); do
  mysql database "DROP TABLE $table"
done

L'option -N de mysql masque les entêtes de colonnes et l'option -B permet d'avoir un résultat brut, exploitable dans la boucle.

On peut également faire le script plus générique suivant :

#!/usr/bin/bash

help="mysql_drop_table_like [options] database pattern

Drop all the mysql tables in database that starts with pattern.

-h: host
-u: user
-pPASSWD: give password
-P: prompt for password
"

usage() {
    echo -e $help
}

pflag=false
Pflag=false
uflag=false
hflag=false

while getopts ":h:u:p:P" opt
do
    case "$opt" in
        h)
            host=$OPTARG; hflag=true;;
        u)
            user=$OPTARG; uflag=true;;
        p)
            passwd=$OPTARG; pflag=true;;
        P)
            Pflag=true;;
        :)
            echo "Option -$OPTARG requires an argument." >&2
            usage; exit 1;;
        \?)
            usage; exit 0;;
    esac
done
shift $((OPTIND-1)) # To get the 1st positional argument with $1

# Check that we have at least 2 positional arguments
if [ $# -lt 2 ] ; then
    echo "Number of positional arguments insuffisant."
    usage
    exit 1
fi

# Cannot provide and ask for password
if $Pflag && $pflag; then
    echo "Cannot provide and ask for password."
    usage
    exit 1
fi

if $hflag; then
    HOST="-h $host"
fi
if $pflag; then
    PASSWD="-p$passwd"
fi
if $Pflag; then
    PASSWD="-p"
fi
if $uflag; then
    USER="-u $user"
fi

mysql="mysql $HOST $PASSWD $USER"
for table in $($mysql $1 -NBe "SHOW TABLES LIKE '$2%'"); do
    $mysql $1 -e "DROP TABLE $table"
done

Utiliser isso pour avoir des commentaires auto-hébergés

2014-06-08T00:00:00+02:00

Lorsque j'ai lancé ce blog, j'utilisais un plugin de pelican pour avoir un système de commentaires statiques. Je ne suis en effet pas un grand fan des commentaires hébergés chez des prestataires externes comme disqus pour des questions de vie privée. Ce plugin me semblait un bon compromis : il ajoute un formulaire grâce à du javascript dans lequel on peut entrer son commentaire qui est ensuite envoyé par mail à l'administrateur du site. Celui-ci doit ensuite copier/coller le contenu du commentaire dans un fichier dédié.

Cela présente l'avantage d'être simple et respectueux de la vie privée bien qu'un peu fastidieux pour l'administrateur. Mais quand on a pas beaucoup de commentaire, ce n'est pas très grave et ça permet de les modérer.

Je me disais que c'était très bien et puis récemment, je suis tombé sur cet article qui présente issos. Isso est un petit logiciel qui vous permet de stocker les commentaires dans une base de données sqlite et de les enregistrer/afficher grâce à un peu de javascript. Cela vous permet de combiner les avantages de l'auto-hébergement et de l'aspect dynamique d'un service comme disqus. Petit plus sympa, isso peut vous envoyer un mail à chaque commentaire ajouté avec la possibilité de les modérer.

C'est simple, efficace et d'après mes tests ça marche plutôt bien. Évidement, ce n'est pas utilisable si vous avez vraiment beaucoup de commentaires, ça reste du sqlite ;-). Il manque également une vraie interface d'administration pour gérer les commentaires.

Voilà un exemple basique de configuration.

[general]

# File location to the SQLite3 database, highly recommended
# to change this location to a non-temporary location!
dbpath = /var/lib/isso/comments.db

# URL to your website. When you start Isso, it will probe
# your website with a simple GET / request to see if it can
# reach the webserver. If this fails, Isso may not be able
# check if a web page exists, thus fails to accept new
# comments.
# You can supply more than one host.
host = http://www.jujens.eu

notify = smtp

[server]
listen = http://localhost:8080/

[moderation]

# Enable comment moderation queue. This option only affects
# new comments. Comments in modertion queue are not visible
# to other users until you activate them.
enabled = false

Pour lancer isso en arrière plan avec sa configuration

/usr/local/bin/isso -c /etc/isso.conf run &

Pour en savoir plus

L'article cité plus haut : http://hackriculture.fr/isso-commentaires-auto-heberges-pour-pelican-et-autres-sites-statiques.html Le site officiel d'isso : http://posativ.org/isso/

Markdown vs creole vs Restructured Text vs org-mode

2014-05-10T00:00:00+02:00

Comme je l'ai déjà détaillé ici, je ne suis pas un grand fan des syntaxes verbeuses à la LaTeX ou HTML et je préfère les langages à balisages légers (et oui, je ne suis pas non plus fan des WYSIWYG). Comme j'ai eu l'occasion d'en tester plusieurs ces derniers temps, je vous propose une petite comparaison.

Markdown

Peut être le plus connus et le plus utilisé. On le retrouve sur Github, Stackoverflow, pelican et dans les commentaires de ce blog :D. La syntaxe est simple ce qui doit expliquer sa popularité.

Malheureusement, le markdown de base n'est pas très complet. Il ne gère pas les tableaux par exemple. Certes, on peut insérer du HTML dans du code markdown pour palier ce problème mais bon, le but c'est justement de pouvoir utiliser quelque chose de plus léger que le HTML. Cela a donc assez logiquement entraîné la création de diverses extensions comme le markdow à la sauce github qui ne sont évidement pas toujours compatibles entre elle.

Ce langage contient aussi un point que je trouve particulièrement mal fait : pour insérer un saut de ligne, on peut ajouter deux espaces à la fin de la dite ligne. Pour moi c'est très mauvais : on ne voit pas si on a modifié ces espaces et tous mes éditeurs de texte sont paramétrés pour enlever les espaces de fin de ligne.

Mais ce qui m'a fait fuir ce langage c'est la possibilité d'ajouter du code que je trouve vraiment pourrie. On peut ajouter du code, soit en l'entourant avec ~~~ soit en ajoutant deux tabulations devant. J'avais déjà testé la syntaxe avec les tildes et ça marchait plutôt bien. Puis en voulant ajouter du code sur ce blog j'ai eu des problèmes pour activer la coloration syntaxique si l'extension table des matières est active. La syntaxe avec les tildes ne fonctionnait plus et j'ai bien galéré avec l'autre. Du coup, j'ai regardé d'autres syntaxes.

Restructured Text

L'autre syntaxe bien supportée par Pelican est le Restructured Text (rst en abrégé). C'est beaucoup plus complet que markdown et ça supporte beaucoup de chose : ajouter des propriétés aux images insérées, les références, sommaire et index… Il faut dire que le langage a été conçu pour remplacer LaTeX pour la documentation de python. Donc, mécaniquement, il faut pas mal d'options. Et je dois dire que le résultat, du point de vue des fonctionnalités offertes en est un concurrent sérieux pour l'export en html. LaTeX garde l'avantage pour l'export pdf car c'est aussi un système de mise en page très pointu (ce dont on a pas forcément besoin pour autre chose que la page de garde cela dit).

Pour être franc, mes premiers tests avec rst n'ont pas été concluant du tout. Premièrement, le fait qu'il soit nécessaire de souligner ces titres avec =, -, ou + suivant le niveau ne me plaît pas particulièrement, je trouve ça un peu lourd. Ici c'est d'autant plus lourd que le soulignement doit faire exactement la taille du titre, sinon rst génère une erreur.

Ensuite, les sous-listes doivent être séparées de la liste parente par un saut de ligne et la puce doit être indentée précisément sous le premier caractère du texte de la liste parente. Le calvaire des indentations en python mais en pire !

Enfin, les tableaux doivent être fait intégralement à la main.

Et puis j'ai trouvé cet article (en) qui m'a réconcilié avec le format. J'utilise désormais le rst-mode pour emacs qui permet de placer le bon nombre de caractères sous les titres avec ^u =, fait l'indentation tout seul. J'ai aussi appris que emacs est capable sans plugin supplémentaire de créer des tableaux ascii compatible avec rst. J'ai donc retenté l'expérience et ce fut concluant. Maintenant, j'admets, j'aime bien et j'ai pris plaisir à écrire mon tuto sur la communication série en arduino avec. Par contre, compte tenu de sa relative verbosité, je le réserve pour les longs articles ou les tutos.

Creole

Encore un autre langage à balise. Il a été créé dans le but d'unifier les langages existants. Il est léger et plutôt complet. Voir par là pour la syntaxe. J'admets avoir été séduit par ce langage simple et efficace. J'ai même fait le plugin pelican pour l'utiliser. Je l'utilise pour les articles de blog assez courts qui n'ont pas besoin de la puissance de rst.

Org-mode

Je n'ai pas grand chose de plus à dire par rapport à mon dernier article : de LaTeX à org-mode. C'est complet et bien intégré avec emacs. Si je m'en suis un peu détourné c'est à cause du manque d'implémentation dans pelican. Il faut impérativement passer par emacs et on perd la possibilité d'utiliser le système de cache de pelican.

Conclusion

Le moins que l'on puisse dire c'est qu'on a énormément de choix. Je suis personnellement très déçu par mardown et j'ai du mal à comprendre pourquoi il est si populaire alors que d'autres langages comme creole sont vraiment bien.

Je pense également utiliser rst pour mes prochains rapport plutôt que LaTeX ou org-mode. Je trouve ce format mieux fait que org-mode bien qu'un peu plus verbeux. Mais je vais certainement continuer à utiliser org-mode pour mes notes.

Une petite sélection de jeu libre pour se détendre

2014-05-07T00:00:00+02:00

Durant les dernières vacances, j'ai voulu me détendre avec quelques jeux libres. J'en ai retenu 3 qui sont simples et distrayants. J'ai donc exclu 0ad et Battle for Wesnoth qui sont des jeux de stratégie un peu trop « prise de tête », pas assez simples (mais très bons quand même).

SuperTuxKart

C'est un jeu de course qui ressemble au célèbre Mario Kart. On y joue seul ou à plusieurs (pas pu tester faute de manette). On a le choix entre plusieurs karts qui s'inspirent tous d'un projet libre. On retrouve donc Tux, Beastie, ElePHPant, … Le jeu dispose d'un mode histoire : le but étant de gagner les courses proposées pour libérer GNU. Le scénario n'est donc pas très profond, mais ce n'est pas ce qu'on lui demande.

Le jeu contient tous les éléments qui font qu'un jeu de course comme ça est bien : nitro, trucs à lancer sur les adversaires (ballon de basket, cake explosif,…), plutôt bons graphismes et de bonnes musiques qui s'accordent bien avec la course.

Captures

Liens et téléchargements

Site officiel : http://supertuxkart.sourceforge.net/
Téléchargement (Disponible dans les dépôts de la plupart des distributions) : http://supertuxkart.sourceforge.net/Downloads

Funguloïds

C'est un jeu assez étrange. Vous êtes une sorte de comète et vous devez collecter des champignons de couleur pour les ramener sur leur platforme tout en évitant des astéroïdes. Vous gagnez alors des points et changer de carte. Cela étant dit, le jeu est vraiment très beau graphiquement et sa musique calme vous permettra de vous reposer tout en vous amusant.

Captures

Liens et téléchargements

Site officiel : http://funguloids.sourceforge.net/
Téléchargement (Disponible dans les dépôts de la plupart des distributions) : http://funguloids.sourceforge.net/download.html

SuperTux 2

Pour faire simple : c'est Tux qui se prend pour Mario sur la banquise. C'est un bon jeu de platforme, simple mais efficace.

Captures

Liens et téléchargements

Site officiel : http://supertux.lethargik.org/
Téléchargement (Disponible dans les dépôts de la plupart des distributions) : http://supertux.lethargik.org/download.html

Mon passage à Pelican

2014-04-22T00:00:00+02:00

Présentation

Pelican est un générateur de site statique écrit en python. Un générateur de site statique est simplement un programme qui transforme des fichiers textes en un site web avec thème, catégorie, … Les plus connus sont jekyll qui est écrit en ruby, middleman en ruby également, octopress qui est basé sur jekyll et nanoc. Mais il y en a beaucoup d'autres.

L'avantage de ce genre de site est qu'ils sont simples, qu'ils n'ont pas besoin de bases de données ou de langages particuliers comme PHP sur votre serveur. Il faut juste un serveur web qui délivre des fichiers. Et ça, ils sont tous capables de le faire. J'ajouterais également la simplicité de rédaction : pas d'éditeur WYSIWYG, juste du texte brut et une syntaxe légère pour y donner du sens. Cela implique également que l'on peut utiliser un gestionnaire de version comme git ou mercurial pour gérer les fichiers (et pour en faire des sauvegardes facilement).

Avant de passer à Pelican, j'ai pu tester Jekyll. Les deux sont très proches, très complets et extensibles via des plugins. Si j'ai préféré Pelican c'est parce que :

Il est en python ce qui me permettra de faire des modifications ou des plugins au besoin (je ne connais pas suffisament ruby pour ça).
Il a un système de cache ce qui évite de devoir recompiller tout les fichiers à chaque fois.

L’installation

Tout est très bien détaillé dans la documentation officielle. J'ai choisi la méthode recommandé : dans un enviromment virtuel, en python 3 (pour être moderne) et à partir de la version git (le plugin des commentaires statiques ne fonctionne pas bien sur la dernière version publiée).

Attention toute fois, en python 3 la commande virtualenv ne fonctionne pas comme il faut. J'ai utilisé la commande python3 -m venv blog pour créer cet environement dans le dossier blog. Le module venv vient par défaut avec python 3. Reste à installer pelican et toutes les bibliothèques avec pip install <bibliothèque>. Pelican a nottament besoin de Markdown. Les autres sont installées comme dépendance par pip. Le support d'Asciidoc demande un peu plus de travail. Allez voir la doc pour plus d'informations.

Ensuite, la commande pelican-quickstart va vous aider à générer la configuration du site. Vous allez devoir répondre à plusieurs questions pour que le site vous corresponde. Point intéressant, cette commande va aussi créer un Makefile pour vous aider à automatiser le processus de création de site. Plus d'infos ci-dessous.

Le site

Par défaut, Pelican supporte les articles écrits en markdown, RestructuredText ou dans une moindre mesure Asciidoc. On écrit simplement l'article dans le dossier content (si vous avez lancez pelican-quickstart) et on l'enregistre avec la bonne extension (.md pour du markdown ou .rst pour RestructuredText).

Une fois l'article écrit, on lance la commande pelican chemin/vers/votre/article et pelican va générer votre site statique dans un dossier nommé output. Si vous avez un Makefile, un simple make html suffira. Pour visualiser votre site sur votre ordinateur, make serve va lancer un serveur sur http://localhost:8000. Simple et efficace.

Les plugins et les thèmes

Un point intéressant : les fonctionnalités de Pelican peuvent être étendu via des plugins. Cela va de l'ajout d'un système de commentaires statiques au rendu des équations LaTeX en passant par une gallerie. Allez par là pour en savoir plus.

J'ai d'ailleur écrit mon propre plugin : creole-reader qui ajoute le support de la syntaxe creole dans pelican. Je ne suis en effet pas un grand fan de Markdown et la syntaxe Rest ne me plait que moyennement. Je crérais peut être aussi un plugin pour org-mode si je n'arrive pas à me faire à Rest (creole est beaucoup moins complet et trop limité pour des long tutos).

Si vous pouvez créer facilement des thèmes à partir du moteur de template Jinja2, vous pouvez aussi prendre un des nombreux thèmes disponibles ici. J'ai choisi dev-random2 (que j'ai un peu adapté).

Conclusion

Mon passage à Pelican est récent mais je suis vraiment séduit par l'outil. Auparavant, mon blog était en Drupal. Cela peut paraître étrange, mais je gère une installation multisite de Drupal, donc ce n'était pas un problème. Par contre, Drupal manque de souplesse pour un blog. D'autant que sur notre installation, c'est soit du texte brut soit du HTML (éventuellement avec CKEditor). C'est d'autant plus pénible que CKeditor supporte très mal le code et à tendance à enlever certaines balise. Peu pratique, idem pour la gestion des révisions c'est pas souple même si ça marche très bien.

Avec pelican, je suis très content de pouvoir utiliser du balisage léger et mercurial pour les révisions. Plus qu'à importer tout mes articles ;-).

Drupal : un an d'utilisation, mes impressions

2014-02-01T00:00:00+01:00

Je suis utilisateur de Drupal depuis environ 1 an maintenant et j’ai donc décidé de partager ce que j’ai appris avec cet outil que j’ai découvert à Centrale Marseille (ECM) grâce au projet multi-assos (qui héberge cet humble blog). Aujourd’hui, j’admets avoir pris goût à l’outil et je suis le webmaster du forum foceen un des plus gros sites de l’installation (et un des plus compliqué aussi).

Avant

Avant d’entrer à l’ECM, je n’avais jamais fait de vrai site web. J’avais appris quelques bases de php et de mysql sur le site du zéro (openclassrooms maintenant). J’avais un peu entendu parler de framework et de CMS mais je n’en pensais pas grand chose de bien. Sans trop caricatirer, je pensais : « Non mais un site ça se code à la main. Les CMS et les framework c’est des machins d’assistés ». Et puis j'ai découvert Drupal.

Drupal

Si vous ne connaissez pas encore Drupal, permettez que je vous présente l'outil. C'est un des CMS les plus utilisés et les plus populaires. Drupal accueille de gros sites (comme celui de la maison blanche) et des plus modestes (comme celui-ci) et globalement de nombreux sites d'entreprises ou d'institutions.

Un des gros avantages de Drupal est sa modularité. Sa communauté très active maintient de très nombreux modules de qualité qui vous permettent de transformer votre Drupal en site de e-commerce, en forum ou plus simplement de lui ajouter des fonctionnalités intéressantes comme un éditeur WYSIWYG. Le tout sans coder une seule ligne. De plus, ces modules viennent avec des interfaces puissantes mais bien faîtes pour les configurer suivant vos besoins. Le tout juste avec votre souris. Ce qui signifie que vous n'avez pas besoin d'être un geek pour être webmaster d'un site. Tout ce fait très bien via l'interface (sauf pour des besoins très spécifiques qui demandent du dévelloppement).

La communauté crée aussi pleins de thèmes et certains sont mêmes adaptatifs. Pas besoin d'être un très bon designer pour avoir un joli site. Plutôt cool non ?

Ce sont toutes ces raisons qui font que Drupal est bien adapté pour les associations de l'école. On est pas des dévelopeurs et cela permet de péréniser les sites web. Car c'est dur de faire un site web (du moins correctement).

Administrer l'installation

En tant que membre du club Drupal, je fais des sites web (et aide ceux qui en font) et administre l'installation. C'est à mon avis la partie la plus intéressante.

Faire des scripts Shell pour automatiser des tâches, faire du git, monter un serveur en local, bosser sur les migartions de drupal,… c'est intéressant et formateur (surtout quand il ne faut rien casser).

C'est dur de faire un site web

Contrairement à ce que peut laisser penser un cours de PHP ce n'est pas simple de faire un site web correctement. Ma (certes assez petite) expérience de webmaster me l'a bien montrée. Sur un site fait par quelqu'un qui est reconnu comme plutôt bon et qui sait coder, il peut y avoir de nombreux problèmes.

Ceux que j'ai vu et qui m'ont posés le plus de problèmes sont :

du code non indenté
les mots de passe stockés en clair dans la base de données (si si, il y en a qui le font)
des accès base de données sans passer par PDO (donc pas de requêtes préparées et des injections SQL faciles à faire)
des données encodées n'importe comment dans une base de données
fonction_1, fonction_2 et fonction_3 qui font la même chose (en tout cas je n'ai pas vu la différence). Et la gestion de version ça sert à quoi ?

Conclusion

Drupal c'est bien ;-). Vous vous prendrez la tête sur l'interface au lieu de vous prendre la tête sur du code mais bon, vous surviverez. Vous tomberez aussi sur des gens qui pense que comme tout se fait à la souris c'est facile et ça ne s'apprend pas. Ça c'est faux. Il vont faire des pages entièrement codé en html sans utiliser les champs et les vues. Ils vous dirons que Drupal c'est pourri et qu'en PHP ils auraient pu le faire facilement. On ne peut pas tout résoudre avec un outil, aussi bien soit-il.