Music Scores As Code

Derrière ce nom pompeux qui peut effrayer, je vais essayer d’expliquer dans cet article comment on peut versionner facilement ses partitions et les publier sur le web.

En cherchant comment mettre de la documentation technique avec des diagrammes PlantUml dans des repos GITLAB et générés avec des pipelines, je me suis mis dans la tête de faire la même chose avec des partitions 🙂

Depuis plusieurs années, j’utilise lilypond pour créer mes partitions. C’est un peu difficile de s’y mettre, mais une fois la syntaxe assimilée, la saisie d’une partition est beaucoup plus efficace. Le rendu des partitions est vraiment optimisé.
Si vous voulez plus de détails sur le pourquoi du comment je vous conseille cette page.

Vous trouverez des exemples sur le site.

J’ai donc eu l’idée de:

  • Stocker ces partitions sur un repo github (jusque là rien d’exceptionnel)
  • Générer automatiquement les partitions au format PDF, PNG et MIDI via une github action (ça commence à devenir intéressant…)
  • Les publier avec les github pages (tant qu’à faire 🙂)

Stockage

Pourquoi stocker dans un référentiel de sources tel que Github ? Pour les non informaticiens : les partitions sont stockées au format texte.

\version "2.12.1"

\header {
  title="Try a little tenderness"
  composer="Harry Woods, Jimmy Campbell & Reg Connely"
  subtitle = "Commitments Version"
  %poet = "Poete"
  instrument = "Piano"
  editor = "L'éditeur"
  %meter=\markup {\bold {"Remarque sur le rhythme"}}
  style = "Soul"
  maintainer = "Alexandre Touret"
  maintainerEmail = "alexandre.touret@free.fr"
  maintainerWeb = "http://blog.touret.info"     
  lastupdated = ""
  source = "Music room"
  footer = "Footer"
  copyright =\markup {\fontsize #-1.5
 "Delivered by A TOURET"}
}
upper=
\relative c'{
  \clef treble
  \time 4/4
  \tempo 4=176
  \key g \major
  
  d'2 (b4 e
  d2 b4 a 
  g2 g2 
  <e g,>2) <fis, c' d> 
  \bar "||"

GIT et GITHUB permettent de versionner facilement et pouvoir faire facilement un retour arrière en cas d’erreur.
Aussi, GITHUB offre des fonctionnalités « sociales » et collaboratives qui facilitent la revue des modifications ( en cas de travail à plusieurs ).
Bref, ça offre la sécurité d’une sauvegarde et la possibilité d’un retour arrière en cas d’erreur.

Générer les partitions avec une github action

Les github actions sont des outils permettant:

GitHub Actions makes it easy to automate all your software workflows, now with world-class CI/CD. Build, test, and deploy your code right from GitHub. Make code reviews, branch management, and issue triaging work the way you want.

J’ai donc décidé de créer un workflow qui permet de générer les partitions au format lilypond.

J’ai mis à disposition le code sur github sous licence GNU GPLv3. Elle est utilisable telle quelle.

Pour créer l’action, il faut créer un fichier action.yml à la racine du repo. Voici le contenu

name: 'Lilypond Generator'
description: 'Run Lilypond tool with the given set of arguments to generate music sheets'
author: '@alexandre-touret'

inputs:
  args:
    description: 'Arguments for Lilyponid'
    required: true
    default: '-h'

runs:
    using: 'docker'
    image: 'Dockerfile'
    args:
      - ${{ inputs.args }}

branding:
  icon: 'underline'
  color: 'blue'

Vous aurez compris que ce fichier fait référence à une image Docker. Cette dernière n’est ni plus ni moins qu’une Debian avec lilypond d’installé.

Pour l’utiliser dans un repo github, on peut créer une action qui l’utilise. Voici un exemple:

jobs:
  build_sheets:
    runs-on: ubuntu-latest
    env:
        LILYPOND_FILES: "*.ly"
    steps:
      - name: Checkout Source 
        uses: actions/checkout@v1
      - name: Get changed files
        id: getfile
        run: |
          echo "::set-output name=files::$(find ${{github.workspace}} -name "${{ env.LILYPOND_FILES }}" -printf "%P\n" | xargs)"
      - name: LILYPOND files considered echo output
        run: |
          echo ${{ steps.getfile.outputs.files }}
      - name: Generate PDF music sheets
        uses: alexandre-touret/lilypond-github-action@master
        with:
            args: -V -f --pdf ${{ steps.getfile.outputs.files }}

A la dernière ligne on peut passer les arguments nécessaires à lilypond.

Publication

La c’est l’étape la plus facile :). Il suffit d’activer les github pages et de commiter et pusher les partitions générées

 - name: Push Local Changes
        run: |
          git config --local user.email "${{ secrets.GIT_USERNAME }}"
          git config --local user.name "${{ secrets.GIT_EMAIL }}"
          git add .
          git commit -m "Add changes" -a
      - name: Push changes
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

Il suffit de créer une page index.md à la racine et d’ajouter des liens vers les partitions générées ( dans mon cas, ça se passe dans le répertoire /docs ).
Vous pouvez trouver un exemple ici.

Conclusion

Voila comment on peut générer un site avec des partitions crées avec Lilypond.
Vous trouverez les différents liens ci-dessous. Peut être que je publierai cette action sur le marketplace une fois que j’aurai publié une documentation digne de ce nom :).

Utiliser des GITHUB Actions pour déployer dans Google Kubernetes Engine

A mes heures perdues, je travaille sur un « POC/side project qui n’aboutira pas et je m’en fiche » basé sur Quarkus. J’ ai choisi d’utiliser les langages et composants suivants :

Oui, tant qu’à faire, autant aller dans la hype …

Mon projet est sur GITHUB. Pour automatiser certaines actions et, disons-le, par fierté personnelle, j’ai choisi d’automatiser certaines actions par la mise en œuvre de pipelines CI/CD.
Depuis peu, GITHUB a intégré un mécanisme de pipeline : GITHUB Actions.

Ça permet, entre autres, de lancer des processus automatisé sur un push ou sur une action pour un commit GIT.

La force de l’outil est, selon moi, de facilement s’intégrer avec beaucoup de services du cloud ( sonarcloud, google cloud, heroku,…). On aime ou on n’aime pas, mais chez Microsoft, l’intégration ils savent faire.

Par exemple, si on veut lancer une compilation lors d’un push, on peut placer un fichier .github/workflows/build.xml avec le contenu :

name: CI

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: Set up JDK 11
        uses: actions/setup-java@v1
        with:
          java-version: 11
      - name: Build with Gradle without testing
        run: ./gradlew build -x test

Coté GITHUB, vous verrez l’exécution sur un écran dédié

Vous pouvez créer autant de workflows que vous souhaitez (si votre projet est en libre accès).
Pour chaque workflow, on peut définir et utiliser des jobs. Les logs d’exécution sont disponibles dans ce même écran:

Worflows implémentés

J’ai choisi d’implémenter les workflows suivants:

  • CI: Build sur la feature branch
  • CD: Build sur master branch et déploiement

On obtient donc dans mon cas:

Ce n’est pas parfait. Loin de là. Dans la « vraie vie », pour une équipe de dev, je l’améliorerai sans doute par un build docker dans les features branches, une validation formelle et bloquante de l’analyse sonar, etc.
Pour un dev perso ça suffit largement. Le contenu de la branche master est compilé et une image docker est crée pour être déployée automatiquement dans GKE.

Analyse SONAR

J’ai choisi d’utiliser sonarcloud pour analyser mon code. C’est gratuit pour les projets opensource. L’analyse se fait simplement:

  sonarCloudTrigger:
    name: SonarCloud Trigger
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: Set up JDK 11
        uses: actions/setup-java@v1
        with:
          java-version: 11
      - name: SonarCloud Scan
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        run: ./gradlew jacocoTestReport sonarqube

Dans ce job j’utilise deux secrets. Ce sont des tokens qui permettent de ne pas stocker en dur les données dans les repos GITHUB.

Création d’une image Docker et déploiement dans le registry GITHUB

Ici aussi, ça se fait simplement. La preuve :

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: Set up JDK 11
        uses: actions/setup-java@v1
        with:
          java-version: 11
      - name: Build in JVM Mode with Gradle without testing
        run: ./gradlew quarkusBuild  [1]
      - name: Branch name
        run: echo running on branch ${GITHUB_REF##*/}
      - name: Build the Docker image Quarkus JVM
        run: docker build -f src/main/docker/Dockerfile.jvm -t docker.pkg.github.com/${GITHUB_REPOSITORY}/music-quote-jvm:latest .  [2]
      - name: Login against github docker repository
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: docker login -u ${GITHUB_ACTOR} -p ${GITHUB_TOKEN}  docker.pkg.github.com   [3]
      - name: Publish the Docker image Quarkus JVM
        run: docker push docker.pkg.github.com/${GITHUB_REPOSITORY}/music-quote-jvm:latest  [4]
  1. Création du binaire
  2. Création de l’image docker en utilisant la commande docker et le Dockerfile fourni par Quarkus
  3. Identification sur la registry Docker de GITHUB
  4. Déploiement de l’image

Pour plus de détails sur la variable GITHUB_TOKEN, vous pouvez lire cet article de la documentation.

Déploiement dans Google Kubernetes Engine

Mon application est pour l’instant architecturée comme suit (attention c’est compliqué):

Pour la déployer dans Google Kubernetes Engine, j’ai besoin d’ implémenter cette « architecture » par les objets Kubernetes suivants:

J’utilise les objets suivants:

  • Des services pour exposer la base de données ainsi que l’application
  • Un deployment pour l’application
  • Des pods car à un moment, il en faut…
  • Un statefulset pour la base de données

Vous pourrez trouver la définition de tous ces objets au format yaml via ce lien. J’ai fait très simple. Logiquement j’aurai du créer un volume pour les bases de données ou utiliser une base de données en mode PAAS.

Pour lancer le déploiement, il faut au préalable créer un secret ( fait manuellement pour ne pas stocker d’objet yaml dans le repository GITHUB) pour se connecter au repo GITHUB via la commande suivante:

kubectl create secret docker-registry github-registry --docker-server=docker.pkg.github.com --docker-username=USER--docker-password=PASSWORD --docker-email=EMAIL

On peut faire pareil pour les connexions base de données. J’ai mis dans un configmap pour ne pas trop me prendre la tête…

Après le déploiement via le pipeline se fait assez simplement:

      [...]
      - uses: GoogleCloudPlatform/github-actions/setup-gcloud@master
        with:
          version: '286.0.0'
          service_account_email: ${{ secrets.GKE_SA_EMAIL }}
          service_account_key: ${{ secrets.GKE_SA_KEY }}
          project_id: ${{ secrets.GKE_PROJECT }}
      # Get the GKE credentials so we can deploy to the cluster
      - run: |-
          gcloud container clusters get-credentials "${{ secrets.GKE_CLUSTER }}" --zone "${{ secrets.GKE_ZONE }}"
      # Deploy the Docker image to the GKE cluster
      - name: Deploy
        run: |-
          kubectl apply -f ./k8s     

J’utilise les « actions » fournies par Google.

Conclusion

Pour que ça marche il y a pas mal d’étapes préalables ( des tokens à générer, un utilisateur technique, …).
J’ai essayé de les référencer dans le README du projet.
Si vous voulez tester l’intégration Kubernetes dans le cloud google, sachez que vous pouvez disposer d’un crédit de 300€ valable un an. Attention, avec ce genre d’architecture, ça part vite…

Vérifier les commit GIT avec GPG

Juste pour un pense bête, voici comment paramétrer GIT et GITHUB/GITLAB pour signer les commits avec GPG.

Configuration GPG

Exécutez la commande suivante :

gpg --full-generate-key

Sélectionnez une clé RSA (question 1) de 4096 bits (question 2).

Une fois cette commande effectuée, vous pouvez récupérer votre clé GPG avec cette commande:

gpg –list-secret-keys –keyid-format LONG

gpg --list-secret-keys --keyid-format LONG alexandre@....
/home/alexandre/.gnupg/pubring.kbx
----------------------------------
sec rsa4096/XXXXXXXXXX 2019-08-09 [SC]
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
uid [ ultime ] Alexandre Touret <mon.mail.github.ou.gitlab@monprovider.fr>
ssb rsa4096/XXXXXXXXXX 2019-08-09 [E]

Ensuite, il faut exécuter cette commande

gpg --armor --export XXXXXXXXXX

Configuration GIT

Indiquez la clé GPG à GIT

 git config --local user.signingkey 6F9D7D5FCE959337

Et indiquez que vous voulez signer tous vos commits

git config --local commit.gpgsign true

Si vous ne faites pas cette dernière commande, vous devrez ajouter l’option -S à chaque exécution de la commande git commit.

Exemple:

 git -a -S -m "Ajout javadoc"

Configuration GITHUB

Sur Github ( il y a la même chose sur gitlab), vous pouvez dans vos paramètres ajouter cette clé . De cette manière, vos prochains commits envoyés seront vérifiés.

 En espérant que ça serve à d’autres 🙂