Deploy automatico per Poisson da GitHub

Supponiamo di avere un sito web statico che vogliamo caricare su Poisson, ad esempio un progetto NodeJS che genera in dist/ o out/ i file da caricare. Come possiamo automatizzare il processo di deploy su Poisson?

Vedremo come deployare il nostro sito, e successivamente come automatizzare il deployment con le GitHub Actions.

Setup manuale

Come primo approccio, potremmo compilare il nostro progetto in locale e poi caricare i file su Poisson utilizzando rsync, ad esempio come segue:

$ npm run build
$ rsync -avz dist/ <username>@poisson.phc.dm.unipi.it:public_html/

(osserviamo che gli / alla fine di dist/ e public_html/ sono importanti per evitare di creare delle cartelle per errore)

GitHub Actions

Per automatizzare questo processo possiamo caricare il nostro progetto su GitHub ed aggiungere un workflow che esegue il build e il deploy ogni volta che facciamo un push sul branch main. Ad esempio, possiamo creare un file .github/workflows/deploy-poison.yaml con quanto segue:

name: Deploy to Poisson
on:
    push:
        branches:
            - main
jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
            - name: Checkout code
              uses: actions/checkout@v4

            - name: Write SSH keys
              run: |
                  install -m 600 -D /dev/null ~/.ssh/known_hosts
                  install -m 600 -D /dev/null ~/.ssh/id_ed25519
                  echo "${{ secrets.SSH_KNOWN_HOSTS }}" > ~/.ssh/known_hosts
                  echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_ed25519

            - name: Setup Node.js
              uses: actions/setup-node@v3
              with:
                  node-version: '23'

            - name: Install dependencies
              run: npm install

            - name: Build
              run: npm run build

            - name: Deploy
              run: rsync -cavz dist/ ${{ secrets.SSH_USER }}@poisson.phc.dm.unipi.it:public_html/

Comando rsync

Il comando rsync ha le seguenti opzioni:

• -c per controllare i file tramite checksum invece che per data e dimensione (che sono sempre diverse visto che stiamo ricosruendo il sito ogni volta con le GitHub Actions)

• -a per copiare ricorsivamente i file e mantenere i permessi

• -v per mostrare i file copiati

• -z per comprimere i file durante il trasferimento

SSH Segreti

Per stabilire una connessione SSH a Poisson dalle GitHub Actions in modo sicuro, dobbiamo aggiungere alcuni segreti alla nostra repository. Vediamo meglio il workflow:

- name: Write SSH keys
  run: |
      install -m 600 -D /dev/null ~/.ssh/known_hosts
      install -m 600 -D /dev/null ~/.ssh/id_ed25519
      echo "${{ secrets.SSH_KNOWN_HOSTS }}" > ~/.ssh/known_hosts
      echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_ed25519

Questa è la parte più importante del workflow, che permette di autenticarsi su Poisson senza dover inserire la password ogni volta (cosa che non possiamo materialmente fare dall GitHub Actions).

Per farlo, creiamo in locale una coppia di chiavi SSH apposta per le GitHub Actions e aggiungiamo la chiave pubblica su Poisson. Per farlo, possiamo seguire questi passaggi:

$ ssh-keygen -t ed25519 -C "deploy@github-actions" -f actions-deploy-key
$ ssh-copy-id -i actions-deploy-key <username>@poisson.phc.dm.unipi.it

Qui generiamo una chiave ssh utilizzando l’algoritmo ed25519 (leggermente più consigliato rispetto a rsa, in particolare ha anche chiavi più corte), -C aggiunge semplicemente un commento alla chiave e -f specifica il file in cui salvare la chiave.

Poi eseguendo cat actions-deploy-key possiamo copiare il contenuto della chiave privata ed aggiungiamo il contenuto in un segreto chiamato SSH_PRIVATE_KEY nella nostra repository GitHub.

Poi, per evitare che la connessione venga rifiutata, eseguiamo in locale anche uno scan delle chiavi SSH di Poisson:

$ ssh-keyscan poisson.phc.dm.unipi.it

(se l’output è vuoto riprovare con ssh-keyscan -4 ...) e copiamo l’output in un segreto della nostra repository chiamato SSH_KNOWN_HOSTS.

Infine possiamo aggiungere anche un segreto SSH_USER con il nostro username o modificare anche direttamente il workflow ed inserire l’username direttamente nel file.

Ora ogni volta che facciamo un push sul branch main il nostro sito verrà automaticamente costruito e caricato su Poisson!