Déploiement Astro.js sur Hostinger avec GitLab CI/CD

Introduction

Automatiser le déploiement d’un projet Astro.js peut vous faire gagner un temps précieux tout en réduisant les erreurs humaines. Dans cet article, nous verrons comment utiliser GitLab CI/CD pour déployer facilement et automatiquement un site Astro.js sur un serveur Hostinger, en passant par une connexion sécurisée SSH.

Pré-requis

1. Serveur Hostinger avec accès SSH

Vérifiez les points suivants avant de commencer :

• Votre plan Hostinger doit inclure l’accès SSH.
• L’accès SSH doit être activé depuis le panneau de contrôle Hostinger.
• Notez vos informations de connexion SSH :
  • Utilisateur (souvent uXXXX ou personnalisé).
  • Hôte (votre domaine ou adresse IP).
  • Port SSH (par ex. 2222, si non standard).

2. Configuration des Clés SSH

Générez une clé SSH si ce n’est pas déjà fait depuis votre terminal local :

bash ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

• Ajoutez la clé publique (~/.ssh/id_rsa.pub) à la liste des clés autorisées dans Hostinger (SSH Keys).
• Conservez votre clé privée (~/.ssh/id_rsa) pour la stocker dans les variables de GitLab CI/CD.

3. Variables dans GitLab : Étape par Étape

Les variables GitLab CI/CD permettent de stocker des informations sensibles ou spécifiques au projet (comme des clés SSH ou des détails de connexion) en toute sécurité. Voici comment configurer correctement ces variables dans GitLab :

Étape 1 : Accéder aux variables CI/CD

1. Connectez-vous à votre instance GitLab.
2. Ouvrez le projet dans lequel vous voulez configurer le pipeline.
3. Cliquez sur Settings (Paramètres) dans le menu vertical de gauche.
4. Dans la section CI/CD, cliquez sur Expand dans la section Variables.

Étape 2 : Ajouter les variables nécessaires

Ajoutez les variables suivantes en cliquant sur le bouton Add Variable. Voici les détails pour chacune :

Étape 3 : Configurer les paramètres de chaque variable

1. Lors de l’ajout de chaque variable, configurez ses options :

   • Key (Clé) : Saisissez précisément le nom de la variable (ex. SSH_UBUNTU_PRIVATE_KEY).
   • Value (Valeur) : Collez la valeur appropriée (détail ci-dessus).
   • Flags (Options) :
     • Masked : ✅ Activez cette option pour masquer la valeur dans les journaux du pipeline.
     • Protected : ✅ Activez cette option pour restreindre l’utilisation à des branches protégées (comme main).

2. Sauvegardez chaque variable en cliquant sur Add Variable.

Étape 4 : Vérifiez les variables dans votre pipeline

1. Une fois les variables configurées, vérifiez que le pipeline peut y accéder.
2. Dans GitLab, allez dans la section CI/CD > Pipelines.
3. Lancez un pipeline manuellement pour valider qu’il a accès et utilise correctement les variables.

À quoi ressemblent les variables dans .gitlab-ci.yml ?

Voici un rappel de leur lien avec votre fichier .gitlab-ci.yml :

variables:
  SSH_KEY: "$SSH_PRIVATE_KEY"                # Clé SSH privée utilisée dans la configuration
  HOST: "$DEPLOY_HOSTINGER_HOST"             # Hôte distant (nom de domaine ou adresse IP)
  PORT: "$DEPLOY_HOSTINGER_PORT"             # Port SSH, souvent personnalisé pour Hostinger (par ex. `22123`)
  USER: "$DEPLOY_HOSTINGER_USER"             # Utilisateur SSH (par ex. u123456)
  DEPLOY_DIR: "$DEPLOY_HOSTINGER_PATH"       # Chemin absolu du dossier distant où sera déployé votre site (par ex. `/home/uXXXX/domains/mon_domaine/public_html`).

Le pipeline GitLab CI/CD

Voici la configuration complète du fichier .gitlab-ci.yml utilisé pour le déploiement de votre projet Astro.js. Il comprend trois étapes : installation, build et déploiement.

yaml stages:

• install
• build
• deploy

Étape 1 : Installer les dépendances Node.js

Cette étape a pour objectif d’installer toutes les dépendances définies dans votre projet, en utilisant la commande npm ci, qui garantit une installation propre en se basant sur le fichier package-lock.json. C’est particulièrement utile pour s’assurer que les versions des dépendances restent consistantes entre les environnements.

Détails importants :

1. Image Docker utilisée : On utilise ici une image officielle de Node.js, dans sa version 18. Cela garantit que le pipeline dispose de l’environnement Node.js adapté pour exécuter les scripts.

2. Commande utilisée (npm ci) : Cette commande :

   • Installe les dépendances en se basant exclusivement sur package-lock.json.
   • Supprime tout fichier existant dans node_modules/ avant chaque installation (idéal pour les environnements CI/CD).

3. Artifacts : Les dépendances sont sauvegardées en tant qu’artifacts pour être partagées et utilisées dans les étapes suivantes du pipeline (comme l’étape de build).

Exemple YAML détaillé

Voici un fichier YAML correctement structuré pour cette étape :

# Étape 1 : Installation des dépendances Node.js
install_deps:
  stage: install    # Étape associée (définie dans "stages" du pipeline)
  image: node:18    # Image Docker officielle de Node.js, version 18
  script:
    - echo "Installation des dépendances..." # Message pour le suivi
    - npm ci                                 # Installation propre des dépendances
  artifacts:
    paths:
      - node_modules/  # Sauvegarde du dossier node_modules pour les autres étapes
    expire_in: 1h       # Artifacts disponibles pendant 1 heure (optionnel)

Étape 2 : Build d’Astro.js

Cette étape a pour but de compiler le site Astro.js afin de générer les fichiers statiques qui seront déployés ultérieurement sur le serveur. Astro utilise la commande npm run build pour construire les fichiers optimisés pour la production, généralement dans un dossier comme dist/.

Détails importants :

1. Image Docker utilisée : On utilise la même image officielle node:18 pour assurer un environnement Node.js cohérent avec l’étape précédente.

2. Dependencies : Cette étape dépend des artifacts produits lors de l’étape install_deps. Cela signifie que tout ce qui a été sauvegardé dans les artifacts de install_deps sera disponible dans cette étape (notamment le dossier node_modules/).

3. Commande utilisée (npm run build) : Cette commande :

   • Exécute le script de build défini dans le fichier package.json d’Astro.js.
   • Produit des fichiers statiques prêts à être déployés dans un dossier (par défaut dist/).

4. Artifacts : Les fichiers générés dans le dossier dist/ sont sauvegardés en tant qu’artifacts pour être utilisés dans l’étape suivante, comme le déploiement.

Exemple YAML détaillé

Voici un fichier YAML complet et structuré pour cette étape :

# Étape 2 : Build du site Astro.js
build_site:
  stage: build     # Étape associée (définie dans "stages" du pipeline)
  image: node:18   # Image Docker Node.js utilisée pour cette étape
  dependencies:
    - install_deps # L'étape dépend des fichiers node_modules/ sauvegardés précédemment
  script:
    - echo "Lancement du build Astro.js..."  # Message utile pour les logs
    - npm run build                          # Génère les fichiers statiques pour le déploiement
  artifacts:
    paths:
      - dist/      # Sauvegarde des fichiers de build pour l'étape suivante
    expire_in: 1h  # Durée de conservation des fichiers générés (optionnel)

Étape 3 : Déployer sur Hostinger

Cette étape gère le déploiement des fichiers générés (dans le dossier dist/) sur votre serveur Hostinger en utilisant le protocole SSH et l’outil rsync. Elle est configurée pour être exécutée uniquement depuis la branche main, ce qui assure que seul le code validé pour la production est déployé.

Détails importants :

1. Image Docker utilisée : L’image Docker utilisée est alpine:latest. Elle est légère et idéale pour installer rapidement des outils comme ssh et rsync.

2. only : Cette étape est déclenchée seulement pour les pipelines exécutés sur la branche main. Cela garantit que seules les modifications validées pour la production sont déployées.

3. before_script : Ce bloc configure l’environnement pour le déploiement :

   • Installation des outils nécessaires (ssh, rsync).
   • Configuration d’une clé SSH temporaire depuis la variable sécurisée SSH_KEY.
   • Ajout de l’hôte distant (Hostinger) à la liste des hôtes connus pour SSH (~/.ssh/known_hosts).
   • Vérification de la connexion SSH au serveur.

4. script : Cette partie utilise rsync pour synchroniser les fichiers du dossier dist/ (local) vers le serveur distant. L’option --delete garantit que les fichiers supprimés localement sont également supprimés à distance, maintenant les deux environnements synchronisés.

5. after_script : Une fois le déploiement terminé, la clé SSH temporaire est supprimée pour renforcer la sécurité.

Exemple YAML détaillé

Voici une version propre et précise de cette étape :

# Étape 3 : Déployer sur Hostinger
deploy:
  stage: deploy                  # Étape associée (définie dans "stages" du pipeline)
  image: alpine:latest           # Image Docker légère pour exécuter les commandes
  only:
    - main                       # Exécuter cette étape uniquement sur la branche "main"
  before_script:
    - apk add --no-cache openssh rsync        # Installation des paquets nécessaires
    - mkdir -p ~/.ssh                         # Préparation du répertoire SSH
    - echo "$SSH_KEY" > ~/.ssh/id_rsa && chmod 600 ~/.ssh/id_rsa  # Configuration de la clé privée
    - ssh-keyscan -p $PORT $HOST >> ~/.ssh/known_hosts            # Ajout de l'hôte distant
    - echo "Test de connexion SSH..."
    - ssh -p $PORT "$USER@$HOST" "echo Connexion réussie !"       # Vérification de la connexion
  script:
    - rsync -avz -e "ssh -p $PORT" --delete dist/ "$USER@$HOST:$DEPLOY_DIR"  # Déploiement avec rsync
  after_script:
    - rm -f ~/.ssh/id_rsa && echo "Clé SSH supprimée."            # Suppression de la clé privée après déploiement

Explications supplémentaires :

1. only : Cela limite l’exécution de l’étape uniquement à la branche main. Ainsi, des branches de test ou de développement ne déclencheront pas d’action de déploiement.

2. Variables dynamiques : Les variables sensibles (comme les identifiants ou les chemins) doivent déjà être définies dans les variables CI/CD de GitLab :

   • $SSH_KEY : Clé SSH privée pour l’accès au serveur (elle est ajoutée au répertoire ~/.ssh/).
   • $HOST : Domaine ou adresse IP du serveur Hostinger.
   • $PORT : Port SSH (par exemple 2222 pour Hostinger).
   • $USER : Nom d’utilisateur pour la connexion SSH.
   • $DEPLOY_DIR : Dossier distant où les fichiers seront déployés (par exemple, /home/uXXXX/domains/mon-domaine.tld/public_html).

3. rsync :

   • Le préfixe -e "ssh -p $PORT" permet de configurer rsync pour utiliser le bon port SSH.
   • L’option --delete garantit que les fichiers supprimés localement sont supprimés sur le serveur, maintenant les deux environnements parfaitement synchronisés.

4. Vérification de la connexion SSH :

   • La commande ssh -p $PORT "$USER@$HOST" "echo Connexion réussie !" vérifie que les identifiants et clés SSH fonctionnent correctement avant le déploiement. Cela permet d’identifier rapidement tout problème de connexion.

5. Nettoyage de la clé SSH :

   • Le fichier id_rsa est supprimé après le déploiement pour des raisons de sécurité.

Résultat attendu :

• Cette étape déploiera avec succès le contenu du dossier dist/ sur votre serveur Hostinger lorsqu’elle est exécutée sur la branche main.
• Les fichiers obsolètes sur le serveur seront supprimés grâce à --delete, garantissant une synchronisation complète.

Tester et Surveiller le Pipeline

1. Assurez-vous que vos branches sont correctement configurées :

   • Seul un commit sur la branche main déclenche ce pipeline (modifiable via le champ only dans l’étape deploy).

2. Allez dans CI/CD > Pipelines dans votre projet GitLab pour surveiller l’exécution :

   • Chaque étape (install, build et deploy) doit être verte ✅.

Gestion des Erreurs

Cas fréquents

1. Permission denied (SSH)

• Vérifiez si votre clé publique est ajoutée dans Hostinger (SSH Keys).
• Assurez-vous que la clé privée est correctement passée dans SSH_PRIVATE_KEY.

2. Rsync error: command not found

• Assurez-vous d’avoir installé rsync via le script apk add --no-cache rsync.

3. Fichiers non copiés

• Vérifiez si le dossier dist/ est correctement généré.
• Assurez-vous que le chemin DEPLOY_DIR correspond au répertoire distant.

Conclusion

Avec cette configuration clé en main, le déploiement de votre projet Astro.js est automatisé avec GitLab CI/CD vers Hostinger via SSH. N’hésitez pas à personnaliser le pipeline pour répondre à d’autres besoins spécifiques, comme l’ajout de tests.

Maintenant, poussez vos commits et regardez votre site Astro.js être déployé automatiquement 🚀 !

Bonne configuration !