pi-appliance, accueil

Spécification de pi-appliance

Statut : cible. Ce document décrit le produit visé. Presque rien n’est encore implémenté : l’état réel et l’avancement sont dans TODO.md. Une section ne passe de « cible » à « réalisé » que lorsque le code correspondant existe.

1. Objet

pi-appliance transforme un Raspberry Pi en appliance : un boîtier personnel, posé à la maison, sur lequel on déploie des services. C’est un nœud de Fog Computing : les services tournent chez l’utilisateur, au plus près de ses données et de ses objets, et restent accessibles depuis internet.

On flashe une image système prête à l’emploi sur la carte SD, et le Pi fonctionne aussitôt, sans installation manuelle.

L’image repose sur trois couches :

Couche Contenu
Système Image standard de Raspberry Pi OS (ex-Raspbian), Lite, 64 bits
Conteneurs Docker Engine et Docker Compose
Produit La couche pi-appliance : console d’administration, marketplace, reverse proxy Traefik, exposition sur internet

1.1 Public visé

pi-appliance s’adresse au grand public : des personnes sans connaissances techniques, qui ne savent ni ce qu’est Docker ni ce qu’est un DNS. En découle, pour toute la suite :

1.2 Licence

pi-appliance est un logiciel libre sous licence GNU Affero General Public License version 3 (AGPL-3.0), fichier LICENSE. Toute personne qui modifie pi-appliance et le met à disposition d’autres utilisateurs, y compris à travers le réseau, doit publier ses modifications sous la même licence. Les applications de la marketplace gardent leur propre licence.

1.3 Objectif de la première version

Une personne sans connaissances techniques, avec un Raspberry Pi neuf, ouvre son Nextcloud depuis internet en moins de 15 minutes après avoir flashé la carte SD, sans aide (hors temps de flashage et de téléchargement des images Docker).

2. Vocabulaire

Terme Sens
Appliance Le Raspberry Pi équipé de l’image pi-appliance.
Console L’interface web d’administration de l’appliance, servie sous /pi-appliance.
Administrateur Compte qui gère l’appliance ; le premier est créé au premier démarrage.
Utilisateur Compte qui accède aux services autorisés.
Invité Compte à durée limitée, pour un partage ponctuel.
Service Une application installée depuis la marketplace : un ou plusieurs conteneurs Docker.
Marketplace Le catalogue des applications installables.
Manifeste La description d’une application de la marketplace (images, volumes, sous-domaine, paramètres, besoins).
Adresse de l’appliance Le nom sous lequel l’appliance est joignable depuis internet : <nom>.pi-appliance.com par défaut, ou un domaine personnel.
Relais Serveur du projet qui rend l’appliance joignable quand la box ne le permet pas (section 7.3).

3. Parcours type

  1. J’achète un Raspberry Pi.
  2. Sur www.pi-appliance.com, je télécharge l’image et je la flashe sur une carte SD en suivant le guide.
  3. Je démarre le Pi.
  4. Le Pi crée un Wi-Fi « pi-appliance ». Je m’y connecte avec mon téléphone : une page s’ouvre, je choisis le Wi-Fi de la maison (ou le câble Ethernet s’il est branché) et je saisis son mot de passe. Le Pi rejoint mon réseau.
  5. J’ouvre la console :
    • depuis un appareil de la maison : https://pi-appliance.local/pi-appliance ;
    • depuis le Pi lui-même (écran et clavier branchés) : https://localhost/pi-appliance.
  6. Je me connecte avec l’identifiant et le mot de passe initiaux, je choisis aussitôt mon propre mot de passe et je donne mon adresse e-mail, que je confirme avec le code reçu.
  7. Je choisis mon adresse : un nom libre <nom>.pi-appliance.com, ou mon propre domaine.
  8. Je crée mes utilisateurs.
  9. Dans la marketplace, je coche les services que je veux et, pour chacun, qui peut y accéder.
  10. pi-appliance télécharge les images Docker, configure Traefik et les certificats, et ouvre chaque service :
    • à la maison, sur le réseau local ;
    • sur internet, à l’adresse https://<service>.<nom>.pi-appliance.com.

4. Image système et matériel

5. Console d’administration

Servie par l’appliance sous /pi-appliance, en HTTPS seulement.

5.1 Premier démarrage (assistant)

  1. Connexion avec l’identifiant initial ; changement de mot de passe obligatoire.
  2. Adresse e-mail de l’administrateur, obligatoire, vérifiée par un code envoyé par e-mail (récupération et alertes, sections 8.5 et 8.6).
  3. Langue de l’interface.
  4. Adresse de l’appliance : <nom>.pi-appliance.com (vérification que le nom est libre) ou domaine personnel (section 7.1).
  5. Test d’accès depuis internet ; guide de la box ou bascule sur le relais si besoin (section 7).
  6. Création des utilisateurs.
  7. Statistiques anonymes : proposées, désactivées par défaut (section 8.4).
  8. Choix des premiers services dans la marketplace.

5.2 Fonctions courantes

Une appliance se gère depuis sa propre console : pas de tableau de bord commun à plusieurs appliances.

5.3 Langues

L’interface est traduite dans les 12 langues de Wikipedia2Book : français, anglais, espagnol, portugais, italien, allemand, néerlandais, turc, chinois, japonais, arabe et persan (ces deux dernières de droite à gauche). Langue détectée d’après le navigateur, modifiable à tout moment. Le français fait foi.

5.4 Versions

Versions numérotées x.y.z. Deux canaux : stable (par défaut) et bêta, au choix de l’administrateur dans la console. La version et le canal sont affichés en bas de chaque page.

6. Marketplace

6.1 Catalogue

6.2 Installer et désinstaller

6.3 Applications de la première version

Application Logiciel Remarques
Fichiers, agenda, contacts Nextcloud Ancien prototype (section 12) : docker-nextcloud/
Partage de fichiers à la maison Samba Réseau de la maison seulement ; ancien prototype (section 12) : docker-samba/
Site web Apache + PHP Ancien prototype (section 12) : docker-apache/
Wiki DokuWiki Sans base de données, tourne sur tous les modèles
Édition de texte à plusieurs Etherpad  
VPN WireGuard Accès au réseau de la maison depuis l’extérieur ; configuration du téléphone par QR code affiché dans la console. Le trafic internet du téléphone ne passe pas par la maison.

Règles propres à ces applications :

Plus tard : caméra (Motion, timelapse : anciens prototypes pi-motion/ et pi-timelaps/, section 12).

6.4 Hors marketplace

6.5 Format des manifestes

Un manifeste est un fichier marketplace/<identifiant>/compose.yaml : un fichier Docker Compose ordinaire, avec une section x-pi-appliance que Docker Compose ignore :

Clé Sens
name, description, category, license Présentation dans la marketplace
icon Icône : tracé SVG (attribut d) sur 24 × 24, dessiné en trait blanc sur la couleur de l’application (charte graphique)
subdomain Nom proposé pour le service, donc son sous-domaine
service, port Service Compose publié par Traefik et son port interne
memory_mb, disk_mb Mémoire et disque minimaux
login application (comptes propres au logiciel) ou console (connexion unique, section 8.1)
access Accès par défaut : public, users ou home (section 8.2)
parameters Variables demandées à l’installation : name (majuscules), label, default, ou generate: true pour un secret tiré au hasard

Le fichier Compose peut utiliser ces variables, plus PI_INSTANCE (nom du service) et PI_HOST (son adresse complète). Les volumes sont des volumes Docker nommés, propres à chaque instance. Le manifeste est refusé (identifiant, icône, sous-domaine, service publié absent, service sans image, port, valeurs inconnues, paramètre invalide ou en double, préfixe PI_ réservé).

Réalisé (première version, paquets marketplace et internal/services) :

7. Accès depuis internet

Objectif : chaque service est joignable à https://<service>.<adresse de l'appliance>, depuis la maison comme depuis internet, avec un certificat valide.

7.1 Adresse de l’appliance

7.2 Accès direct

Par défaut, la box redirige les ports 80 et 443 vers le Pi. L’appliance tente de l’obtenir par UPnP ; sinon, la console guide l’utilisateur pas à pas pour sa box, puis vérifie l’accès depuis internet.

7.3 Relais

Quand l’accès direct est impossible (CGNAT, 4G, box verrouillée), l’appliance ouvre un tunnel sortant vers un relais du projet, qui fait suivre le trafic ; l’adresse de l’appliance pointe alors vers le relais. Bascule automatique, signalée dans la console. Ancien prototype : tunnel autossh all-pi/autossh.sh (section 12).

Offre :

8. Utilisateurs, accès et sécurité

8.1 Connexion unique

8.2 Qui accède à un service

À l’installation, pour chaque service : public sur internet, utilisateurs connectés ou maison seulement. La valeur par défaut vient du manifeste (Samba : maison seulement ; site web : public ; Nextcloud : utilisateurs connectés). Modifiable ensuite dans la console.

8.3 Console

8.4 Règles

8.5 Récupération de l’accès

8.6 Alertes par e-mail

L’appliance prévient les administrateurs, par le service d’envoi du projet :

Chaque type d’alerte peut être désactivé dans la console.

9. Sauvegarde et mises à jour

9.1 Sauvegarde

9.2 Mises à jour

Les mises à jour de pi-appliance, des services et du système sont proposées : la console les signale, l’utilisateur clique pour les appliquer. Rien n’est mis à jour sans son accord, y compris les correctifs de sécurité de Raspberry Pi OS : ceux-ci sont signalés en évidence dans la console et rappelés par e-mail (section 8.6) tant qu’ils ne sont pas appliqués. Une mise à jour de service ratée revient automatiquement à la version précédente (section 6.2).

10. Architecture

flowchart LR
    Internet((Internet)) --> Box[Box / routeur]
    Internet -. "sans accès direct" .-> Relais[Relais du projet]
    Relais -. "tunnel sortant" .-> Traefik
    LAN((Réseau de la maison)) --> Traefik
    Box -- "80 / 443" --> Traefik
    subgraph Pi["Appliance — Raspberry Pi OS + Docker"]
        Traefik[Traefik<br/>reverse proxy + Let's Encrypt]
        Console[Console pi-appliance<br/>/pi-appliance<br/>+ fournisseur d'identité]
        S1[Service A]
        S2[Service B]
        Traefik --> Console
        Traefik --> S1
        Traefik --> S2
        Traefik -- "authentification déléguée" --> Console
        S1 -- "OpenID Connect" --> Console
        Console -- "API Docker, labels Traefik" --> S1
        Console -- "API Docker, labels Traefik" --> S2
    end
    subgraph Projet["Services du projet — Pi du projet"]
        Adresses[Service d'adresses<br/>zone pi-appliance.com]
        Relais
        Mail[Service d'envoi d'e-mails]
        Stats[Statistiques anonymes]
    end
    Console -- "catalogue" --> Catalogue[(Dépôt GitHub<br/>marketplace)]
    Console -- "adresse publique" --> DDNS[(DuckDNS)]
    Console -- "réservation, signe de vie" --> Adresses
    Console -- "alertes, récupération" --> Mail
    Console -. "si accepté" .-> Stats
    Adresses -- "alias nom → DuckDNS" --> DDNS

10.1 Choix techniques

Partie Choix
Console (API, Docker, utilisateurs, DNS dynamique) Go, bibliothèque standard net/http : un seul binaire statique, peu de mémoire, même langage que Docker, Compose et Traefik
Interface web HTML, CSS et JavaScript sans framework, intégrés au binaire (embed)
Configuration de Traefik Labels Docker posés sur les conteneurs des services
Manifestes de la marketplace YAML au format Docker Compose, avec des métadonnées en plus
Fabrication de l’image Shell et pi-gen
Fournisseur d’identité Intégré à la console Go (OpenID Connect, forward auth Traefik, TOTP)
DNS dynamique DuckDNS

Réalisé : squelette de la console (cmd/pi-appliance, internal/console). Le binaire sert la page d’accueil de la console sous /pi-appliance/ (/pi-appliance redirige vers /pi-appliance/) et GET /pi-appliance/api/health, qui renvoie {"status": "ok", "version": "…"}. Il écoute en HTTP sur :8080 (option -addr) : HTTPS sera assuré par Traefik devant lui. La version est fixée à la compilation (-ldflags "-X main.version=…", dev sinon). Le workflow « Go » (.github/workflows/go.yml) lance go vet et go test et construit le binaire arm64 à chaque push.

10.2 Services du projet

Quatre services centraux, hébergés par le projet sur un Raspberry Pi du propriétaire du projet :

Service Rôle Sans lui
Adresses Réservation des noms <nom>.pi-appliance.com, alias vers DuckDNS, signes de vie, libération après 90 jours Pas de nouvelle adresse ; les adresses existantes continuent de marcher
Relais Tunnel pour les appliances sans accès direct (section 7.3) Ces appliances sont injoignables depuis internet ; l’accès direct n’est pas touché
Envoi d’e-mails Codes de vérification, récupération, alertes (sections 8.5, 8.6) Ni récupération par e-mail ni alertes ; le fichier reset reste possible
Statistiques Réception des statistiques anonymes acceptées Rien de visible pour l’utilisateur

Une appliance continue de fonctionner, à la maison comme en accès direct, quand ces services sont arrêtés. Ces services sont eux aussi sous AGPL-3.0, publiés dans ce dépôt.

11. Exigences non fonctionnelles

12. Arborescence du dépôt

Chemin Contenu
README.md Présentation du projet
LICENSE Texte de la licence AGPL-3.0
CLAUDE.md Instructions pour les agents et paramètres des skills
.claude/skills/ Sous-module : skills partagés gmoulard/claude_skills
docs/ Source du site GitHub Pages www.pi-appliance.com (index.html, site.css, CNAME, _config.yml, _layouts/) ; guide utilisateur (guide-utilisateur.md), spécification, TODO, notes ; charte graphique (charte-graphique.md) ; logo/ : logo retenu (framboise/) et pistes (SVG)
go.mod Module Go github.com/gmoulard/pi-appliance
cmd/pi-appliance/ Programme principal de la console
internal/console/ Serveur web de la console ; web/ : interface intégrée au binaire
internal/services/ Installation et désinstallation des services (Docker Compose)
marketplace/ Catalogue : un manifeste <application>/compose.yaml par application (6.5)
.github/workflows/go.yml Tests et construction du binaire arm64

Les prototypes cités dans ce document (all-pi/, linux-tool/, docker-apache/, docker-nextcloud/, docker-samba/, pi-motion/, pi-timelaps/, RaspController/) ont été retirés du dépôt ; ils restent dans l’historique git, au commit 4ee13f9.

13. Site www.pi-appliance.com

Dans les mêmes langues que la console (section 5.3).

Site et console suivent la même charte graphique : framboise, ludique et colorée, pensée d’abord pour le téléphone, polices du système seulement. Le site est publié par GitHub Pages depuis le dossier docs/ (docs/index.html, docs/CNAME) ; les documents Markdown du dossier (guide, spécification, TODO, charte, logos) y deviennent des pages à la même charte (docs/_config.yml, docs/_layouts/default.html). Réalisé : la page d’accueil (présentation, trois étapes, applications, adresse, téléchargement), en français ; l’image prête à flasher et la réservation d’adresse y sont annoncées pour plus tard.

14. Hors périmètre

15. Questions ouvertes

16. Ordre de construction

  1. Local : image, console, marketplace et services sur le réseau de la maison.
  2. Internet : adresse <nom>.pi-appliance.com, accès direct, relais.
  3. Le reste : connexion unique, sauvegardes, VPN, site d’inscription.