deployment.md – Inky EIP

1  Vue d’ensemble

Ce document explique comment est structuré le dépôt Inky, quels workflows CI/CD sont exécutés automatiquement à chaque changement, et comment le projet est compilé, empaqueté et déployé pour les trois livrables principaux :

Livrable	Description	Cible
InkyOS	Image Alpine Linux minimaliste avec pilotes audio/vidéo, configuration du GPIO et runtime Node 20 LTS	Raspberry Pi 5 (ARM64)
InkyStation	Service Node.js (NestJS) sans interface graphique qui orchestre la narration locale et dialogue avec l’API	Conteneur Docker (amd64 / arm64)
InkyWeb	Application React + Vite servant l’interface d’écriture et de monitoring	Cloudflare Pages + Workers

---

2  Pré‑requis

Matériel

• Poste de développement sous Linux (Ubuntu 22.04 LTS recommandé) ou macOS 13+
• Accès à un Raspberry Pi 5 pour les tests sur cible

Logiciel

• Git >= 2.42
• Docker >= 26.0 et Docker Compose v2
• Node >= 20 LTS + pnpm >= 9
• qemu-user-static (pour builds cross‑architecture)
• Accès aux Secrets GitHub (token de publication, clés SSH, variables env)

---

3  Structure du dépôt

/inky
├── apps/
│   ├── inky‑station/     # service NestJS
│   └── inky‑web/         # SPA React
├── os/
│   ├── build‑scripts/    # scripts de génération InkyOS
│   └── overlay/          # fichiers copiés dans l’image
├── ci/
│   └── templates/        # jobs YAML réutilisables
├── .github/
│   ├── workflows/        # pipelines GitHub Actions
│   └── dependabot.yml
└── README.md

• Monorepo pnpm : chaque application est un workspace. Les dépendances communes sont dédupliquées au niveau racine.
• Les scripts Bash dans os/build‑scripts/ produisent une image .img.xz flashable.

---

4  Workflows CI/CD

Événement	Branche	Jobs déclenchés
push, pull_request	main, release/*	lint → test → build
release (tag)	v*	publish‑docker, upload‑os‑image, deploy‑web
schedule (02:00 UTC)	main	dependabot‑update

4.1  Lint & Test

• ESLint, Prettier et markdown‑lint
• Vitest pour InkyWeb, Jest pour InkyStation
• Artéfacts de couverture générés au format lcov

4.2  Build

1. Cache pnpm 💾
2. Construction multi‑arch via buildx (linux/arm64, linux/amd64)
3. Compression de l’image InkyOS (xz ‑9) et publication comme artéfact

4.3  Publication

• Docker Hub : inkytop/inkystation:{sha} + latest
• GitHub Releases : InkyOS {version}.img.xz

---

5  Build local

# Cloner
 git clone git@github.com:inky‑lab/inky.git && cd inky

# Installer les dépendances
 pnpm install ‑r

# Lancer tous les services en local
 docker compose up ‑d

• Les containers sont créés à partir de docker‑compose.dev.yml.
• http://localhost:5173 sert l’interface InkyWeb. L’API web répond sur :3000.

8  Surveillance et journalisation

Service	Stack	Tableau de bord
Logs applicatifs	n8n	Logs generaux
Métriques	Prometheus	/grafana/d/inky‑metrics
Alertes	n8n	Discord #inky‑alerts

---