Homemade PCs

L'orchestration CI/CD redéfinie pour l'auto-hébergement : Déployez vos projets depuis GitHub vers n'importe où, en toute autonomie.

🏗 Aperçu Technique

Homemade PCs n'est pas un simple dashboard ; c'est une plateforme d'automatisation complète conçue selon une architecture distribuée. Le système sépare les responsabilités entre :

1. Le Cerveau (Core API) : Une API RESTful FastAPI qui gère l'état global, les webhooks GitHub et la persistance des données.
2. Les Bras (Runners) : Des workers isolés capables d'exécuter des tâches complexes (Shell, SSH) et de manipuler des espaces de travail éphémères.
3. Le Visage (Frontend) : Une interface React moderne pour visualiser les pipelines en temps réel.

Cette séparation assure la scalabilité et la sécurité, permettant au runner d'opérer dans des environnements isolés ou distants sans compromettre le serveur principal.

✨ Fonctionnalités Clés

• Intégration GitHub Native & Webhooks : Détection automatique des push sur la branche principale. Le système build dynamiquement un pipeline (Build -> Deploy) en réponse aux événements GitHub.
• Orchestration de Jobs Distribués : Architecture Maître/Esclave où l'API délègue l'exécution à des services "Runners" autonomes via HTTP, avec remontée d'état (Pending -> Running -> Finished/Failed) en temps réel.
• Exécution & Déploiement via SSH : Capacité native à se connecter à des serveurs distants pour déployer des artefacts. Le JobRunner gère intelligemment les clés SSH et les contextes de sécurité.
• Gestion d'Artefacts Dynamique : Transfert automatique des fichiers (ex: tarballs générés au build) entre l'espace de travail local du runner et le serveur distant avant l'exécution des commandes de déploiement.

🛠 Stack Technique

Domaine	Technologies
Frontend	React 19, TypeScript, Context API (State Management), React Router v7, Axios
Backend API	Python 3.10+, FastAPI, Pydantic (Validation), Motor (Async MongoDB Driver)
Worker / Runner	Python, AsyncSSH (Secure Remote Execution), Docker API, Shell Executors
Base de Données	MongoDB (NoSQL pour la flexibilité des logs de jobs et schémas JSON)
DevOps & Infra	Docker Compose, Ngrok (Exposition Webhooks), Tailscale (Réseau privé)

🚀 Installation & Usage

Le projet est entièrement conteneurisé. Pour le lancer localement :

1. Cloner le projet

   git clone https://github.com/votre-user/homemade_pcs.git
   cd homemade_pcs

2. Configurer les variables d'environnement Créez un fichier .env à la racine (basé sur l'exemple) :

   # Exemple de configuration
   SSH_KEY=~/.ssh/id_rsa
   FRONTEND_URL=http://localhost:8080
   RUNNER_API_TOKEN=votre_token_securise
   NGROK_AUTHTOKEN=votre_token_ngrok

3. Lancer la stack complète

   docker-compose up --build -d

4. Accéder à l'application

   • Dashboard : http://localhost:8080
   • API Docs : http://localhost:8000/docs
   • Ngrok Tunnel (pour GitHub) : http://localhost:4040

💡 Challenge Technique & Apprentissage

Le Défi : La continuité des données dans un environnement distribué.

Un défi majeur a été de gérer le déploiement d'artefacts (code compilé) sur un serveur distant via le Runner. Le runner exécute des étapes de build localement (créant une archive .tar), mais l'étape suivante (déploiement) se passe sur une machine distante via SSH.

La Solution : J'ai implémenté une logique contextuelle intelligente dans le JobRunner. Lorsqu'une étape de type ssh est détectée, le runner inspecte son espace de travail local, identifie les artefacts générés par les étapes précédentes, et les transfère automatiquement (scp via asyncssh) vers le serveur cible avant d'exécuter la commande de déploiement. Cela abstrait la complexité du réseau pour l'utilisateur final qui définit simplement : "Build" puis "Deploy".