Cours

Appearance

La dev-box : votre environnement de développement dans Docker ​

Document présentant l'installation et l'utilisation de la dev-box, votre environnement de développement complet dans Docker.

Sommaire

Introduction ​

La dev-box est un environnement de développement complet qui tourne dans un seul conteneur Docker. À l'intérieur, vous avez une vraie machine Linux (Arch Linux) dans laquelle vous installez, en une commande, les langages dont vous avez besoin : PHP, Laravel, Python, Node.js, Java, etc.

Vous ne « lancez » pas la dev-box comme un logiciel : vous vous y connectez en SSH, exactement comme vous le feriez sur un serveur. Vos fichiers, eux, restent visibles sur votre ordinateur : vous pouvez coder dans le terminal de la dev-box (avec Neovim, déjà configuré) ou avec votre éditeur habituel (VSCode, PhpStorm, etc.).

Conteneur ou machine virtuelle ?

Un conteneur n'est pas une machine virtuelle : il partage le noyau de votre machine, il est donc beaucoup plus léger. Si la notion est encore floue, l'aide-mémoire Docker est un bon point de départ.

Que contient la dev-box ? ​

La dev-box contient les éléments suivants :

  • Des environnements de développement à installer en une commande (devbox dev-env) : PHP et Composer, Laravel, Symfony, Node.js, Python, Java, Go, Rust, .NET, Flutter, des outils audio et vidéo, etc.
  • Des bases de données à la demande (devbox dbs) : MariaDB, MySQL, PostgreSQL, Redis, MongoDB, SQL Server.
  • Docker dans la dev-box : docker run et docker compose fonctionnent à l'intérieur (grâce à Podman).
  • Un terminal prêt à l'emploi : zsh, tmux, Neovim (LazyVim), lazygit, yazi (gestionnaire de fichiers), fzf, etc.
  • Un catalogue d'outils en ligne de commande à installer au besoin (devbox tui) : btop, lazydocker, pgcli, etc.
  • Les agents de code en ligne de commande (Claude Code, Codex, opencode, etc.).
  • De quoi créer des applications iPhone et iPad sans Mac (devbox dev-env ios), et les installer sur un vrai appareil, avec le câble ou en Wi-Fi (voir Des applications iPhone et iPad).
  • Une aide pas à pas pour tout ce qu'une commande ne peut pas faire à votre place (devbox help) : un compte à créer, un téléchargement, un câble à brancher, un fichier à modifier sur votre machine.

Pourquoi c'est intéressant ? ​

  • Le même environnement pour tout le monde. Fini le « chez moi ça marche » : toute la classe a les mêmes versions.
  • Rien à installer sur votre machine, à part Docker. L'installation tient en une commande, et vous voulez tout supprimer ? Un dossier à effacer, et c'est tout.
  • Vous installez uniquement ce dont vous avez besoin. Un menu, vous cochez Laravel et Python, c'est prêt.
  • Vos données survivent. Votre dossier personnel et vos projets sont stockés dans des volumes : mettre à jour la dev-box ne supprime rien.
  • Vous travaillez comme sur un vrai serveur Linux. SSH, terminal, services : les réflexes que vous prenez ici sont ceux que vous utiliserez en production (voir par exemple Installer Docker sur une Debian).
  • Votre environnement vous suit partout. Avec Tailscale, vous retrouvez la même dev-box depuis le lycée, chez vous ou sur une tablette (voir Votre dev-box partout avec Tailscale).
  • Une seule commande à retenir : devbox. Elle liste tout ce que la dev-box sait faire, avec un menu.
  • Rien ne se met à jour dans votre dos. La dev-box vous prévient quand une mise à jour est disponible, c'est vous qui décidez quand l'appliquer.

Prérequis ​

Pour fonctionner, vous devez avoir installé Docker et Docker Compose sur votre machine. Pour cela, il vous suffit d'installer Docker Desktop :

Docker Desktop

Il est possible que Docker Desktop vous demande de créer un compte. Vous pouvez le faire, mais ce n'est pas obligatoire.

Il est également possible que Docker Desktop vous demande de mettre à jour votre WSL. Pour cela, il vous suffit de suivre les instructions :

  • Ouvrir un terminal (cmd, powershell, etc.)
  • Exécuter la commande suivante : wsl --update

Vous avez également besoin d'une clé SSH : c'est elle qui vous permet d'entrer dans la dev-box, sans mot de passe. Si vous n'en avez pas encore, suivez l'aide-mémoire La clé SSH (une seule commande : ssh-keygen -t ed25519).

Installation & Lancement ​

L'installation tient en une commande. Pas besoin de Git ni de télécharger le code de la dev-box : un script récupère l'image déjà construite et la démarre pour vous. Dans votre terminal (sous Windows, dans Ubuntu : voir En plus : Windows et WSL 2) :

bash
curl -fsSL https://cours.brosseau.ovh/devbox.sh | sh

Pas de curl sur votre machine ? wget fait la même chose : wget -qO- https://cours.brosseau.ovh/devbox.sh | sh.

Une mauvaise pratique, pourtant très répandue

Cette commande envoie le script téléchargé directement au shell, qui l'exécute. Vous croiserez ce type d'installation partout, mais c'est une mauvaise pratique :

  • vous exécutez du code sans l'avoir lu, avec vos droits, sur votre machine ;
  • si le téléchargement est coupé en plein milieu, le shell exécute un script tronqué, avec des résultats imprévisibles.

Le bon réflexe : télécharger avant d'exécuter. On récupère le script, on le lit (q pour quitter), puis on le lance :

bash
curl -fsSLo devbox.sh https://cours.brosseau.ovh/devbox.sh
less devbox.sh
sh devbox.sh

Prenez ce réflexe, pour la dev-box comme pour n'importe quel script trouvé sur Internet.

Le script vérifie que Docker est bien là, puis vous pose quelques questions. Entrée garde la valeur proposée, et tout reste modifiable plus tard dans le fichier .env. Si gum est installé sur votre machine, les questions sont plus agréables (une liste pour choisir, un bouton oui / non), mais ce n'est pas nécessaire. À la fin, il vous laisse dans le dossier ~/dev-box (un nouveau terminal y est ouvert : exit vous ramène là où vous étiez).

Installer gum (facultatif)

gum est un petit outil qui rend les questions des scripts plus lisibles (c'est lui que vous voyez dans la vidéo plus bas). À installer avant de lancer le script :

  • Ubuntu (et donc WSL), Debian :
bash
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install gum
  • macOS : brew install gum
  • Arch Linux : sudo pacman -S gum

Sans gum, le script pose exactement les mêmes questions, en texte simple.

QuestionCe que je vous conseille de répondre
Install directoryEntrée : la dev-box s'installe dans ~/dev-box
Unix user inside the boxEntrée : l'utilisateur dev
TimezoneEntrée : le fuseau horaire de votre machine
Language of the boxEntrée : la langue de votre machine (fr_FR.UTF-8 met le menu devbox et les astuces de connexion en français)
Access (tailscale or ssh)ssh pour commencer (Tailscale est présenté plus bas)
GitHub user whose public keys are allowed inVotre pseudo GitHub si vous y avez ajouté votre clé SSH (le script récupère les clés de votre compte), sinon Entrée pour passer
Public key of this machine allowed inEntrée : le script a trouvé votre clé publique dans ~/.ssh. Les clés GitHub et celle de votre machine sont toutes autorisées
Add another key?Entrée (non), sauf si vous voulez autoriser une autre machine : chemin d'un .pub, la clé elle-même ou github:pseudo, puis la question revient
SSH port on this hostEntrée : le port 2222
Address the SSH port listens onEntrée : 127.0.0.1, la dev-box n'est accessible que depuis votre machine
GitHub tokenFacultatif, voir ci-dessous
Dev environmentsPar exemple laravel python (voir Installer vos environnements)
Turn podman on?y si vous avez besoin des bases de données (voir les bases de données)
Pass the GPU to the box?Posée uniquement si votre machine a une carte graphique utilisable : Entrée (oui), voir La carte graphique
Pull the image and start the box now?Entrée : oui, le script télécharge l'image et démarre la dev-box

Et Tailscale ?

Pour démarrer, l'accès ssh est le plus simple. Mais gardez Tailscale en tête : avec lui, votre dev-box devient accessible de partout, au lycée, à la maison ou depuis une tablette, avec vos projets et vos serveurs toujours en place, sans rien ouvrir sur votre box Internet. Vous pourrez l'activer à tout moment : tout est expliqué dans Votre dev-box partout avec Tailscale.

Le script écrit ensuite le fichier ~/dev-box/.env avec vos réponses, puis, après la dernière question, télécharge l'image (environ 2 Go, quelques minutes la première fois) et démarre la dev-box. À la fin, il vous affiche la commande pour vous connecter.

Le token GitHub, c'est quoi ?

Pendant l'installation de ses outils, la dev-box interroge beaucoup GitHub. Sans compte, GitHub limite le nombre de requêtes, et une installation peut échouer à cause de cette limite (surtout si toute la classe partage la même connexion). Un token GitHub sans aucun droit (aucune case cochée) suffit à lever cette limite : vous pouvez le créer dans les paramètres de votre compte GitHub.

C'est facultatif : vous pouvez laisser vide et l'ajouter plus tard dans le .env (GITHUB_TOKEN=...).

Voir votre site depuis le navigateur ​

Accès par Tailscale ?

Bonne nouvelle, vous n'avez rien à faire : tous les ports de votre dev-box sont accessibles depuis votre réseau Tailscale (par exemple http://dev-box:8000 pour un serveur lancé avec --host=0.0.0.0). Cette partie ne concerne que l'accès par SSH.

Par défaut, seul le port SSH est ouvert. Pour voir dans votre navigateur les sites que vous lancerez dans la dev-box, il faut rendre le port 8000 accessible. Dans le dossier ~/dev-box, créez (ou complétez) le fichier compose.override.yaml :

yaml
services:
  dev-box:
    ports:
      - "127.0.0.1:8000:8000"

Si vous avez répondu y pour Podman, ce fichier existe déjà : ajoutez simplement les deux lignes ports sous dev-box:, sans toucher au reste.

Cette ligne redirige le port 8000 de votre machine vers le port 8000 de la dev-box : c'est exactement le même principe que dans l'aide-mémoire Installer Docker sur une Debian. Relancez ensuite la dev-box pour prendre en compte le changement :

bash
cd ~/dev-box
docker compose up -d

Se connecter ​

bash
ssh -p 2222 dev@localhost

À la première connexion, SSH vous demande si vous faites confiance à cette machine : répondez yes. Et voilà, vous êtes dans la dev-box 🎉

Vous pouvez suivre ce que fait la dev-box avec docker compose logs -f, depuis le dossier ~/dev-box (Ctrl + C pour quitter les logs, la dev-box continue de tourner).

Première utilisation

Lors du premier démarrage, la dev-box prépare votre dossier personnel et installe ses outils (et les environnements demandés) en tâche de fond. Cela peut prendre plusieurs minutes : pas de panique si tout n'est pas encore là à la première connexion.

À la première connexion, la dev-box vous propose une visite guidée de deux minutes. Je vous conseille de l'accepter ; vous pourrez la relancer plus tard avec devbox tour.

Démo, de la commande d'installation à la première connexion (dans la vidéo, gum est installé, d'où l'apparence des questions ; l'image était déjà téléchargée, et la visite guidée est remise à plus tard pour aller à l'essentiel) :

Pour aller plus loin : installer depuis le dépôt Git

Le script d'installation est la méthode conseillée. Vous pouvez aussi cloner le dépôt et construire l'image vous-même, par exemple pour tester une modification de la dev-box :

bash
git clone https://github.com/c4software/dev-box.git
cd dev-box
cp .env.example .env
# Modifiez le .env (TS_DISABLE, SSH_AUTHORIZED_KEYS, etc.), puis :
docker compose up -d --build

La construction de l'image prend nettement plus de temps que son téléchargement.

Démo de cette méthode, de zéro à la première connexion (dans la vidéo, le .env pointe sur l'image déjà construite avec DEVBOX_IMAGE=ghcr.io/c4software/dev-box:latest, ce qui évite la construction) :

Tous les détails sont dans la page installation manuelle du dépôt.

Installer vos environnements ​

La dev-box démarre légère : c'est à vous d'installer les langages dont vous avez besoin. Une seule commande :

bash
devbox dev-env

Un menu s'ouvre : choisissez « Install environments », cochez les environnements avec x, puis validez avec Entrée. Par exemple, pour les TP de cette année : laravel (qui installe aussi PHP, Composer et Node.js) et python.

Vous préférez sans menu ? C'est la même chose en une ligne :

bash
devbox dev-env laravel python

Quelques commandes utiles :

  • devbox dev-env --list : la liste des environnements disponibles, ceux installés sont marqués d'une étoile.
  • devbox dev-env --info laravel : ce que l'environnement installe (et ce qu'une suppression laisse en place).
  • devbox dev-env --remove python : supprime un environnement (vos projets ne sont jamais touchés).
Que se passe-t-il derrière ?

Les environnements sont installés avec mise, un gestionnaire de versions : chaque outil est déclaré dans ~/.config/mise/config.toml, dans votre dossier personnel. C'est pour cette raison qu'ils survivent à une mise à jour de la dev-box.

PHP fait exception : le compiler prendrait plusieurs minutes, il est donc déjà intégré à l'image (avec Composer, Xdebug et les extensions habituelles). devbox dev-env php vérifie simplement qu'il est prêt.

Les environnements donnés lors de l'installation sont notés dans le .env (DEV_ENVS="laravel python") : ils sont réinstallés automatiquement s'ils manquent, même sur une dev-box toute neuve. Vous pouvez compléter cette ligne à tout moment (puis docker compose up -d). Conséquence : un environnement listé dans DEV_ENVS ne peut pas être supprimé avec --remove, il faut d'abord le retirer du .env.

Utilisation ​

Démo, un projet Laravel (comme dans le TP Introduction à Laravel) puis Python :

Dans cette vidéo, je :

  1. installe Laravel et Python avec le menu devbox dev-env ;
  2. crée un projet Laravel avec composer create-project, comme dans le TP ;
  3. ouvre un second panneau tmux (Ctrl + Espace puis v) pour lancer le serveur avec php artisan serve --host=0.0.0.0 ;
  4. affiche le site dans le navigateur, sur http://localhost:8000 ;
  5. ajoute une route /ping dans routes/web.php avec Neovim, puis la teste avec curl et dans le navigateur ;
  6. crée un petit script Python, toujours avec Neovim, et l'exécute.

Le résultat dans le navigateur de votre machine :

Le projet Laravel servi par la dev-box, affiché dans le navigateur

Pourquoi --host=0.0.0.0 ?

Par défaut, php artisan serve (comme php -S) n'écoute que sur 127.0.0.1, c'est-à-dire à l'intérieur de la dev-box. Avec --host=0.0.0.0, le serveur accepte aussi les connexions qui arrivent de l'extérieur du conteneur, donc de votre navigateur.

Les commandes à retenir :

CommandeCe qu'elle fait
devboxMenu avec toutes les commandes de la dev-box
devbox dev-envInstalle ou supprime des environnements (menu)
devbox dbs mariadbDémarre MariaDB (voir les bases de données)
devbox tuiInstalle des outils en ligne de commande (btop, etc.)
devbox statusÉtat de la dev-box (outils, bases, mises à jour)
devbox helpAide pas à pas pour ce que vous devez faire vous-même (devbox help ios, devbox help podman, etc.)
devbox updateMet à jour les outils, quand vous le décidez
devbox changelogCe qui a changé dans les dernières versions
devbox tourRelance la visite guidée
devbox overrideCe que vous avez modifié, et comment revenir en arrière
devbox diagnosticCherche ce qui ne va pas (voir la FAQ)

Le terminal : tmux et Neovim ​

En vous connectant, vous arrivez dans une session tmux : si votre connexion SSH coupe, vos commandes (un serveur par exemple) continuent de tourner, et vous les retrouvez à la connexion suivante. Tous les raccourcis tmux commencent par Ctrl + Espace, puis :

  • v : coupe l'écran en deux, un panneau à droite ;
  • o : passe d'un panneau à l'autre ;
  • z : met le panneau courant en plein écran (et inversement) ;
  • c : ouvre une nouvelle fenêtre, n et p pour passer à la suivante ou à la précédente.

L'éditeur de la dev-box est Neovim, configuré avec LazyVim : coloration, autocomplétion et analyse du code (PHP, Python, etc.) sont déjà en place. Au tout premier lancement, Neovim télécharge ses extensions : laissez-le travailler une minute.

Vous n'êtes pas à l'aise avec Neovim ? Pas de panique : vos projets sont aussi sur votre machine (voir Où sont les fichiers ?), vous pouvez donc les ouvrir dans VSCode et garder la dev-box pour les commandes.

Les bases de données ​

devbox dbs démarre une base de données dans un conteneur, à l'intérieur de la dev-box. Pour cela, il faut autoriser la dev-box à lancer ses propres conteneurs (Podman).

Si vous avez répondu y à la question « Turn podman on? » de l'installation, c'est déjà fait, passez directement à la commande devbox dbs mariadb ci-dessous. Sinon, complétez votre compose.override.yaml (dans ~/dev-box) :

yaml
services:
  dev-box:
    ports:
      - "127.0.0.1:8000:8000"
    devices:
      - /dev/net/tun
      - /dev/fuse
    security_opt:
      - seccomp=unconfined
      - systempaths=unconfined
      - apparmor=unconfined

Puis dans le fichier .env, passez PODMAN_ENABLE à true et relancez avec docker compose up -d. En cas d'oubli, pas de panique : devbox dbs vous rappelle ces étapes. Ensuite, dans la dev-box :

bash
devbox dbs mariadb

MariaDB est alors disponible sur 127.0.0.1:3306, avec l'utilisateur root et un mot de passe vide :

php
$pdo = new PDO("mysql:host=127.0.0.1;dbname=ma-base", "root", "");
Que se passe-t-il derrière ?

La dev-box est elle-même un conteneur. Pour lancer MariaDB, elle démarre un conteneur dans son conteneur, grâce à Podman (un équivalent de Docker, qui accepte d'ailleurs les mêmes commandes docker run, docker compose, etc.).

Pour que ça fonctionne, il faut assouplir certaines protections du conteneur (security_opt). C'est sans risque pour un environnement de développement sur votre machine, mais c'est pour cette raison que l'option est désactivée par défaut.

Au-delà de PHP ​

La dev-box ne se limite pas au développement web en PHP. Voici ce que vous pouvez faire d'autre, sans rien installer sur votre machine.

D'autres langages ​

Python, Java, Go, Rust, .NET, Node.js, Bun, Deno, Flutter, Swift, Ruby, Elixir, etc. : tout passe par devbox dev-env. La démo ci-dessus installe Python à côté de Laravel, et les deux cohabitent sans problème. Pour Python, l'outil uv est installé en même temps : il gère vos dépendances et vos environnements virtuels.

Audio, vidéo et images ​

devbox dev-env media installe de quoi télécharger, convertir et analyser des fichiers audio, vidéo et images : ffmpeg, yt-dlp, des optimiseurs d'images (oxipng, pngquant, jpegoptim, cwebp), exiftool (lire ou effacer les métadonnées d'une photo, dont la position GPS) et mediainfo. Bonus : avec ffmpeg installé, le gestionnaire de fichiers yazi affiche l'aperçu des vidéos.

Réseau, bases de données et Ansible ​

Vous êtes en SISR ? Les outils de base sont déjà là : dig, nslookup, nc, whois, traceroute, ping, ip. devbox dev-env network ajoute nmap, tcpdump, iperf3, mtr et doggo (un dig plus lisible). Les commandes qui demandent les droits administrateur passent par sudo, sans mot de passe : sudo nmap -sS 192.168.1.0/24, sudo tcpdump -i any port 80. Attention tout de même, la dev-box est un conteneur : tcpdump ne voit que son propre trafic, pas celui de votre ordinateur ni du réseau local.

Pour interroger les bases de devbox dbs, psql et mariadb sont fournis. devbox dev-env db-clients ajoute mongosh (MongoDB), mycli (MariaDB et MySQL, avec autocomplétion) et usql (un seul client pour presque toutes les bases, SQL Server compris).

Enfin, devbox dev-env ansible installe Ansible et ansible-lint : la dev-box devient votre poste d'administration, et vos cibles sont vos machines virtuelles ou les serveurs du labo, joints en SSH.

Docker dans la dev-box ​

Une fois Podman activé (voir les bases de données), vous pouvez utiliser les commandes Docker habituelles dans la dev-box : docker run, docker build, docker compose up. C'est idéal pour tester le docker-compose.yml d'un projet ou suivre l'aide-mémoire Docker. La commande devbox tui lazydocker vous installe même une interface pour gérer vos conteneurs.

Des outils en ligne de commande ​

Certains outils sont déjà là : lazygit (Git en mode visuel), yazi (un gestionnaire de fichiers, avec aperçu des images), fzf (recherche floue), etc. D'autres s'installent à la demande avec devbox tui : btop (moniteur système), pgcli (client PostgreSQL), atac (client d'API, un équivalent de Postman), etc.

Besoin d'un paquet Arch Linux qui n'est pas dans le catalogue ? devbox pkg add <paquet> l'installe et le réinstalle automatiquement après chaque mise à jour de la dev-box.

La carte graphique ​

Si votre machine a une carte graphique Intel, AMD (ou celle d'un Raspberry Pi), la dev-box peut s'en servir : ffmpeg encode et décode alors la vidéo beaucoup plus vite, et OpenGL et Vulkan fonctionnent. Les cartes NVIDIA ne sont pas prises en charge.

Si vous avez répondu oui à la question « Pass the GPU to the box? », c'est déjà en place. Sinon, devbox help gpu donne les étapes (une ligne à ajouter dans compose.override.yaml). Ensuite, dans la dev-box :

  • devbox gpu : l'état de la carte graphique, et ce qui manque ;
  • devbox gpu install : installe les pilotes ;
  • devbox gpu test : encode 10 secondes de vidéo avec la carte graphique, puis avec le processeur, pour comparer (il faut devbox dev-env media).

Les agents de code ​

Claude Code, Codex, opencode, pi et omp sont disponibles directement dans le terminal : ils s'installent tout seuls la première fois que vous les lancez. devbox agent permet de choisir votre agent par défaut, de le lancer dans le dossier courant et de suivre votre consommation.

Codex et son bac à sable

Codex exécute ses commandes dans un bac à sable qui demande les mêmes réglages que Podman. Si vous avez activé Podman, rien à faire. Sinon, recopiez le bloc « Codex » du fichier compose.override.example.yaml dans votre compose.override.yaml, puis docker compose up -d : sans lui, toutes les commandes lancées par Codex échouent.

Des applications iPhone et iPad ​

Normalement, développer pour iPhone demande un Mac et Xcode. Avec la dev-box, vous pouvez écrire, compiler, signer et installer une application iOS depuis Linux, sur un vrai iPhone ou iPad. Elle s'appuie sur deux projets Open Source : xtool, qui remplace Xcode en ligne de commande, et omarchy-apple-dev, qui l'adapte à Arch Linux et comble ce qui lui manque.

Avant de commencer

  • Pas de simulateur : l'application tourne sur un vrai iPhone ou iPad.
  • Une machine x86_64 uniquement (un PC classique, Intel ou AMD) : l'environnement ne fonctionne pas sur un Raspberry Pi ni sur un Mac à puce Apple (M1, M2, etc.). Avec un Mac, utilisez plutôt Xcode directement.
  • Un compte Apple : un identifiant Apple gratuit suffit pour compiler et installer vos applications par câble ; la clé d'API du programme développeur payant ajoute le Wi-Fi et la publication. La connexion par mot de passe passe par des interfaces privées d'Apple : il est conseillé d'utiliser un identifiant Apple créé pour l'occasion plutôt que votre compte personnel.
  • Du temps et de la place : le fichier de Xcode à télécharger pèse plusieurs Go, et la première installation prend plusieurs minutes.

À tout moment, devbox help ios réaffiche toutes les étapes ci-dessous, avec les cas particuliers.

Pour mettre tout ça en pratique, la série de TP iOS sans Mac déroule un hello world en Swift, en Flutter et en Kotlin Multiplateforme, compilé et installé depuis votre machine avec le script devbox-build.sh.

1. Installer l'environnement ​

bash
devbox dev-env ios

Cette commande installe Swift, Python et les outils iOS. Leur compilation prend quelques minutes la première fois. À la fin, elle affiche les étapes qui restent à faire, celles qui demandent votre compte Apple ou un câble.

2. Le SDK iOS et votre compte Apple (une seule fois) ​

Le SDK iOS (les bibliothèques d'Apple : UIKit, SwiftUI, etc.) ne peut pas être distribué : il faut le récupérer dans Xcode.

  1. Regardez la version de Swift de la dev-box : swift --version.
  2. Dans votre navigateur, téléchargez le Xcode qui correspond sur developer.apple.com (connexion avec un identifiant Apple) : Xcode 27 pour Swift 6.4, Xcode 26 pour Swift 6.3. Vous obtenez un fichier .xip.
  3. Déposez ce fichier dans le dossier personnel de la dev-box, c'est-à-dire ~/dev-box/data/home sur votre machine.
  4. Dans la dev-box :
bash
devbox ios

La commande vous laisse choisir le .xip, construit le SDK, le vérifie, vous propose de supprimer le .xip (gardez-le si vous avez la place : il resservira après une mise à jour de Swift), puis vous connecte à votre compte Apple. Choisissez le mode 1 (mot de passe) avec un identifiant Apple gratuit : e-mail, mot de passe, puis le code reçu sur vos appareils. Le mode 0 (clé d'API) est réservé au programme développeur payant d'Apple. Si vous avez sauté la connexion, lancez devbox ios login ; après un échec (mot de passe ou code erroné) ou pour changer de compte, devbox ios logout d'abord.

devbox ios status affiche ensuite l'état : SDK, connexion Apple, appareils associés en Wi-Fi ; devbox ios devices liste les appareils branchés.

3. Brancher l'iPhone ou l'iPad (une seule fois) ​

Par défaut, un conteneur Docker ne voit pas les appareils USB de votre machine. Deux cas :

La dev-box tourne sur la machine où l'iPhone est branché (Linux)

Sur votre machine, dans ~/dev-box/compose.override.yaml, ajoutez sous dev-box: :

yaml
services:
  dev-box:
    volumes:
      - /dev/bus/usb:/dev/bus/usb
    device_cgroup_rules:
      - 'c 189:* rmw'

Si une clé volumes ou device_cgroup_rules existe déjà, ajoutez-y simplement la ligne (une deuxième clé du même nom serait refusée). Toujours sur votre machine, empêchez son propre usbmuxd (le service qui dialogue avec l'iPhone) de garder l'appareil, puis relancez la dev-box :

bash
sudo systemctl mask --now usbmuxd   # « unmask » pour revenir en arrière
docker compose up -d

Puis dans la dev-box, branchez et déverrouillez l'appareil :

bash
devbox pkg add usbmuxd   # une seule fois
devbox ios devices       # répondez « Faire confiance » sur l'appareil, puis relancez

Après une reconstruction de la dev-box, l'appareil vous redemandera de lui faire confiance.

La dev-box tourne sur une autre machine, ou sous Windows ou macOS

Docker Desktop (Windows et macOS) ne transmet pas l'USB aux conteneurs. Dans ce cas, c'est votre machine qui gère l'USB, et la dev-box lui parle à travers votre connexion SSH :

  1. Sur votre machine, installez le service qui dialogue avec l'iPhone : sous Linux le paquet usbmuxd (Arch : sudo pacman -S usbmuxd), sous macOS il est déjà là, sous Windows il est installé avec iTunes ou l'application Appareils Apple. Branchez l'appareil, déverrouillez-le et faites-lui confiance.
  2. Connectez-vous à la dev-box en emmenant ce service avec vous :
bash
ssh -R 27015:/var/run/usbmuxd dev@dev-box          # Linux et macOS
ssh -R 27015:127.0.0.1:27015 -p 2222 dev@localhost # Windows (PowerShell)
  1. Dans cette session de la dev-box :
bash
export USBMUXD_SOCKET_ADDRESS=127.0.0.1:27015
devbox ios devices

Ajoutez la ligne export à votre ~/.zshrc pour ne plus avoir à la taper. Avantage de cette méthode : rien à modifier dans compose.override.yaml, et une reconstruction de la dev-box ne redemande pas de faire confiance. Les détails sont dans devbox help ios-usb.

4. Votre première application ​

Les TP décrivent l'application dans un fichier project.yml (XcodeGen), à côté du code Swift, et la construisent avec devbox ios xcode : la dev-box génère le projet Xcode, compile, signe, installe et lance l'application. Le plus simple est de le faire depuis votre machine, avec le script devbox-build.sh du dépôt de la dev-box, posé dans le dossier du projet (tout est expliqué dans le support de préparation) :

bash
cd ~/dev-box/data/projets/Hello   # sur votre machine, à côté de project.yml
./devbox-build.sh                 # compile, signe, installe et lance l'application
./devbox-build.sh build           # compile seulement
./devbox-build.sh logs            # les logs de l'application
./devbox-build.sh --help          # toutes les étapes et options

Le script vérifie que la dev-box tourne et qu'elle est prête pour iOS, puis lance devbox ios xcode dans la dev-box (docker exec). Dans la dev-box, la même chose s'écrit devbox ios xcode (devbox ios xcode --help). Avec un identifiant Apple gratuit, l'installation passe par le câble ; avec une clé d'API, elle peut aussi passer par le Wi-Fi (plus bas).

La première compilation prend quelques minutes, les suivantes sont rapides. Sur l'appareil, la première fois :

  • s'il vous le demande, activez le mode développeur : Réglages, Confidentialité et sécurité, Mode développeur (l'appareil redémarre), puis relancez l'installation ;
  • si l'application est bloquée au premier lancement (« Développeur non approuvé ») : Réglages, Général, VPN et gestion de l'appareil, votre compte, puis « Faire confiance ».

Une signature de 7 jours

Avec un identifiant Apple gratuit, Apple limite la signature à 7 jours et à 3 applications installées à la fois : passé ce délai, l'application ne s'ouvre plus. Relancez simplement ./devbox-build.sh pour la renouveler.

Sans le câble : le Wi-Fi (iOS 27) ​

À partir d'iOS 27, avec une connexion par clé d'API et une fois l'appareil associé avec le câble, la dev-box peut installer, lancer et lire les logs de vos applications en Wi-Fi :

  1. Une seule fois, l'appareil branché en USB : devbox ios pair. L'association est gardée dans votre dossier personnel : elle survit à une reconstruction de la dev-box. Elle contient une clé privée, gardez-la comme une clé SSH.
  2. Sur l'appareil, activez le Wi-Fi et installez l'application Tailscale, connectée au même réseau Tailscale que la dev-box. tailscale status, dans la dev-box, donne son adresse (100.x.y.z).
  3. Dans le dossier d'un projet Xcode :
bash
devbox ios xcode --wifi 100.x.y.z        # compile, installe et lance
devbox ios xcode logs --wifi 100.x.y.z   # les logs
export IOS_WIFI=100.x.y.z                # pour ne plus taper --wifi

Ou, depuis votre machine, avec le script des TP : ./devbox-build.sh run --wifi 100.x.y.z (./devbox-build.sh pair fait l'étape 1).

Attention : avec un identifiant Apple gratuit, et pour les projets Flutter, le câble reste obligatoire. Les étapes et les pannes courantes sont dans devbox help ios-wifi.

Pour aller plus loin ​

  • Un projet Xcode existant (.xcodeproj ou project.yml de XcodeGen) : devbox ios xcode le compile sous Linux, le signe, l'installe et le lance. devbox ios xcode --help liste les options (--configuration Release, etc.).
  • Kotlin Multiplateforme : devbox ios kmp construit la partie iOS d'un projet Kotlin Multiplateforme, que Gradle ignore sous Linux (il faut aussi devbox dev-env java), et devbox ios xcode --kmp :shared construit l'application complète (avec devbox-build.sh : la ligne APP_KMP=":shared" en tête du script, voir le TP Kotlin Multiplateforme).
  • Déboguer : device-run.sh --lldb lance l'application avec le débogueur, pymobiledevice3 syslog live affiche les logs de l'appareil et pymobiledevice3 crash pull ./crashes récupère ses rapports de plantage.
  • Publier : ship.sh produit le .ipa pour l'App Store, ship.sh --upload l'envoie sur TestFlight (programme développeur payant).
  • Flutter : c'est possible aussi, voir flutter/README.md dans ~/.local/share/omarchy-apple-dev, ou le TP Flutter (devbox-build.sh reconnaît un projet Flutter et appelle flutter/build.sh, par USB uniquement).

Une mise à jour de Swift demande de reconstruire le SDK : devbox help ios (étape 5) explique comment faire.

Votre dev-box partout avec Tailscale ​

Jusqu'ici, la dev-box tourne sur votre ordinateur et vous vous y connectez depuis ce même ordinateur. C'est déjà très bien, mais la dev-box a été pensée pour aller plus loin : une seule dev-box, accessible depuis toutes vos machines. Elle peut tourner sur votre PC, sur un serveur ou même sur un Raspberry Pi 5, et vous la retrouvez depuis le lycée, depuis chez vous ou depuis une tablette, avec vos projets, vos onglets tmux et vos serveurs toujours en place.

C'est Tailscale qui rend ça possible.

Tailscale, c'est quoi ? ​

Tailscale crée un réseau privé (un VPN) entre vos appareils, où qu'ils soient. Chaque machine y reçoit un nom : votre dev-box s'appelle simplement dev-box. Vous installez Tailscale sur votre ordinateur (ou votre téléphone), la dev-box a déjà Tailscale intégré, et les deux se voient comme s'ils étaient sur le même réseau local.

  • Rien à ouvrir sur votre box Internet : aucun port n'est publié, la dev-box n'est pas visible depuis Internet.
  • Pas de clé SSH à copier : c'est votre compte Tailscale qui vous authentifie.
  • Gratuit pour un usage personnel.

Et Headscale ?

Tailscale s'appuie sur un serveur de coordination hébergé par l'entreprise Tailscale. Headscale est une alternative Open Source à ce serveur, que vous pouvez héberger vous-même. La dev-box fonctionne avec les deux : il suffit de renseigner l'adresse de votre serveur dans TS_LOGIN_SERVER.

Activer Tailscale ​

Le plus simple est de choisir Tailscale dès l'installation : c'est d'ailleurs la réponse par défaut à la question « Access (tailscale or ssh) ». Le script affiche alors l'adresse à ouvrir dans votre navigateur pour ajouter la dev-box à votre réseau Tailscale.

Vous avez commencé en SSH classique ? Vous pouvez passer à Tailscale à tout moment :

  1. Créez un compte sur tailscale.com et installez Tailscale sur votre ordinateur.
  2. Dans le fichier ~/dev-box/.env, passez TS_DISABLE à false.
  3. Relancez la dev-box et affichez les logs :
bash
docker compose up -d
docker compose logs -f
  1. Les logs affichent une adresse : ouvrez-la dans votre navigateur pour ajouter la dev-box à votre réseau Tailscale. Cette étape n'est à faire qu'une seule fois.
  2. Depuis n'importe quel appareil connecté à votre réseau Tailscale :
bash
ssh dev@dev-box

Selon les réglages de votre compte, Tailscale peut vous demander de confirmer la connexion dans votre navigateur.

Ce que Tailscale vous apporte en plus ​

  • Voir vos sites sans rien configurer. Un serveur lancé avec --host=0.0.0.0 est directement accessible sur http://dev-box:8000 depuis toutes vos machines, sans compose.override.yaml.

  • Partager un site en cours de développement. devbox serve 8000 publie le port sur votre réseau Tailscale et affiche l'adresse à ouvrir, même pour un serveur qui n'écoute que sur 127.0.0.1. devbox serve off 8000 arrête le partage.

  • Envoyer des fichiers entre vos machines. devbox tailscale send envoie un fichier vers un autre de vos appareils (un menu vous demande lequel), devbox tailscale receive réceptionne ceux qu'on vous envoie dans ~/inbox. Dans le gestionnaire de fichiers yazi, le raccourci c puis t fait la même chose.

  • Partager un dossier entre vos machines. devbox tailscale share partage le dossier courant avec vos autres machines (Taildrive), devbox tailscale open parcourt les partages des autres dans yazi, et devbox tailscale get en copie les fichiers dans le dossier courant. devbox tailscale unshare arrête le partage. Votre réseau Tailscale doit l'autoriser : les lignes à ajouter sont dans la page d'accès citée ci-dessous.

Tous les détails (auth key, Headscale, règles d'accès) sont dans la page accès à la box du dépôt.

Configuration ​

La configuration de la dev-box se fait en modifiant les fichiers du dossier ~/dev-box de votre machine :

  • .env : écrit par le script d'installation avec vos réponses, il contient les réglages de la dev-box (utilisateur, SSH, Tailscale, bases de données, etc.)
  • compose.override.yaml : contient vos réglages propres à votre machine (ports supplémentaires, dossiers partagés, limites de mémoire, etc.)

Les principales variables du .env :

  • DEVBOX_IMAGE : l'image à utiliser (ghcr.io/c4software/dev-box:latest, l'image déjà construite).
  • USER_NAME : votre nom d'utilisateur dans la dev-box (dev par défaut).
  • TZ : le fuseau horaire.
  • LANG : la langue de la dev-box, par exemple fr_FR.UTF-8 ou C.UTF-8 (anglais). En français, le menu devbox et les astuces affichées à la connexion sont traduits ; le reste (messages des commandes, documentation) reste en anglais.
  • TS_DISABLE : true pour se connecter en SSH classique, false pour passer par Tailscale.
  • SSH_AUTHORIZED_KEYS : la ou les clés publiques autorisées à se connecter (une par ligne).
  • SSH_PORT : le port SSH sur votre machine (2222 par défaut).
  • SSH_BIND : l'adresse sur laquelle ce port écoute (127.0.0.1 : votre machine uniquement).
  • PROJECTS_DIR : le dossier de votre machine qui contient vos projets (./data/projets par défaut).
  • PODMAN_ENABLE : true pour pouvoir lancer des conteneurs (et donc des bases de données) dans la dev-box.
  • DEV_ENVS : les environnements à installer automatiquement au démarrage, par exemple DEV_ENVS="laravel python".
  • GITHUB_TOKEN : le token GitHub facultatif (voir l'installation).

Après chaque modification, relancez la dev-box avec docker compose up -d (depuis ~/dev-box).

Qu'est-ce que j'ai changé ?

À force de personnaliser votre dev-box (configuration de Neovim, outils ajoutés, réglages du .env, etc.), il est facile d'oublier ce que vous avez modifié. Dans la dev-box, devbox override liste tout ce qui diffère de la configuration d'origine, et donne pour chaque point la commande qui permet de revenir en arrière. Elle ne modifie rien : elle se contente d'afficher. devbox override --diff montre le détail des modifications dans les fichiers.

C'est la première commande à lancer si votre dev-box ne se comporte pas comme celle de votre voisin.

Où sont les fichiers ? ​

Vos projets doivent être placés dans le dossier ~/projets de la dev-box. Ce dossier correspond au dossier ~/dev-box/data/projets sur votre machine : c'est le même dossier, vu des deux côtés.

Vous pouvez donc ouvrir ~/dev-box/data/projets dans VSCode sur votre machine, et lancer vos commandes (php, composer, npm, python, etc.) dans la dev-box.

Votre dossier personnel (configuration, historique, outils installés) est dans ~/dev-box/data/home. Ces deux dossiers survivent aux mises à jour de la dev-box.

Attention

Le dossier data contient tout votre travail. Ne le supprimez pas, et pensez à versionner vos projets avec Git (voir l'aide-mémoire Git).

Sous Windows, le dossier est côté Ubuntu : voir Où sont vos fichiers sous Windows ?.

En plus : Windows et WSL 2 ​

Vous êtes sous Windows ? Voici ce qu'il faut préparer avant l'installation, et où retrouver vos fichiers ensuite.

Sous Windows, WSL 2 est obligatoire : la dev-box s'installe et se lance dans WSL 2 (le Linux intégré à Windows), avec Ubuntu, et pas directement depuis PowerShell ou un autre terminal Windows. Si ce n'est pas déjà fait :

  1. Dans un terminal PowerShell, installez Ubuntu : wsl --install -d Ubuntu, puis redémarrez si Windows vous le demande.
  2. Dans Docker Desktop, ouvrez Settings, puis Resources, puis WSL integration, et activez l'intégration pour Ubuntu.
  3. Ouvrez le terminal Ubuntu (depuis le menu Démarrer) : c'est dans ce terminal que vous lancerez toutes les commandes de cette page.

Vérifiez que Docker répond bien depuis Ubuntu avec docker compose version.

Restez dans votre dossier Linux

Lancez l'installation depuis votre dossier personnel Linux (~, c'est-à-dire /home/<vous>), jamais depuis /mnt/c/... : le disque Windows vu depuis WSL est très lent et ne gère pas les droits des fichiers Linux. L'installation vous prévient d'ailleurs si vous êtes au mauvais endroit.

Votre clé SSH doit aussi exister côté Ubuntu : si ls ~/.ssh/*.pub ne donne rien dans le terminal Ubuntu, lancez-y ssh-keygen -t ed25519.

Où sont vos fichiers sous Windows ? ​

Le dossier est dans Ubuntu (WSL) : depuis l'Explorateur Windows, vous le retrouvez sous Linux, puis Ubuntu, puis home/<vous>/dev-box/data/projets. Pour VSCode, le plus confortable est de lancer code ~/dev-box/data/projets depuis le terminal Ubuntu (avec l'extension WSL de VSCode).

FAQ ​

Comment voir mon site dans le navigateur ? ​

Dans la dev-box, lancez le serveur en écoutant sur toutes les interfaces :

bash
php artisan serve --host=0.0.0.0   # Laravel
php -S 0.0.0.0:8000                # PHP « classique »

Votre site est alors accessible à l'adresse suivante : http://localhost:8000.

⚠️ Il faut avoir créé le compose.override.yaml avec la ligne ports (voir Voir votre site depuis le navigateur). ⚠️

Besoin d'un autre port (par exemple 5173 pour Vite) ? Ajoutez une ligne - "127.0.0.1:5173:5173" sous ports, puis relancez avec docker compose up -d.

Comment accéder à MariaDB depuis mon PC ? ​

Si vous souhaitez utiliser un client graphique sur votre machine, comme DBeaver, ouvrez d'abord un tunnel SSH, puis connectez-vous sur localhost:3306 :

bash
ssh -p 2222 -L 3306:127.0.0.1:3306 dev@localhost

🚨 Les bases ne redémarrent pas toutes seules. Après un redémarrage de votre machine, relancez devbox dbs mariadb : vos données sont conservées. 🚨

Et MySQL, PostgreSQL, MongoDB ? ​

Même principe : devbox dbs mysql, devbox dbs postgres, devbox dbs mongodb, devbox dbs redis, etc. La commande devbox dbs --list affiche l'image, le port et l'état de chaque base. Pour PostgreSQL, l'utilisateur est postgres (sans mot de passe) ; pour MongoDB, l'utilisateur est admin et le mot de passe admin123.

MariaDB et MySQL utilisent tous les deux le port 3306 : une seule des deux peut tourner à la fois. devbox dbs --stop mariadb arrête une base sans rien supprimer.

Où est PHPMyAdmin ? ​

Il n'y en a pas, volontairement. Je vous conseille DBeaver avec le tunnel SSH ci-dessus : il fonctionne avec toutes les bases de données, pas seulement MySQL.

Comment tester l'envoi de mails ? ​

La dev-box ne contient pas de serveur mail, mais vous pouvez démarrer Mailpit (l'équivalent moderne de MailHog) en une commande, une fois Podman activé :

bash
docker run -d --name mailpit -p 8025:8025 -p 1025:1025 axllent/mailpit

Le serveur SMTP est alors disponible sur le port 1025 de l'adresse 127.0.0.1, et l'interface web sur le port 8025 (à ajouter dans ports du compose.override.yaml pour l'ouvrir dans votre navigateur).

Comment arrêter la dev-box ? ​

Depuis le dossier ~/dev-box de votre machine :

bash
docker compose stop   # Arrête la dev-box
docker compose start  # La redémarre

docker compose down supprime le conteneur, mais pas vos fichiers : ils sont dans le dossier data.

Comment mettre à jour ? ​

Deux niveaux de mise à jour :

  • Les outils (environnements, Neovim, agents, etc.) : devbox update dans la dev-box.
  • L'image elle-même (Arch Linux, PHP, etc.) : relancez simplement la commande d'installation (ou retéléchargez le script et relancez sh devbox.sh). Il détecte la dev-box existante, télécharge la dernière image et redémarre la dev-box, sans jamais toucher à votre .env, à votre compose.override.yaml ni au dossier data. Vous pouvez aussi, depuis ~/dev-box, lancer docker compose pull && docker compose up -d.

La dev-box vous indique à la connexion quand une mise à jour est disponible, et devbox changelog vous montre ce qui a changé.

Comment désinstaller la dev-box ? ​

Depuis votre machine :

bash
cd ~/dev-box
docker compose down --rmi all

Puis supprimez le dossier ~/dev-box. Attention : c'est ce dossier qui contient data, donc vos projets et votre dossier personnel. Sous Linux, certains fichiers appartiennent à root : il faut alors sudo rm -rf ~/dev-box.

Quelque chose ne fonctionne pas, que faire ? ​

Pas de panique, la dev-box sait s'examiner elle-même. Dans l'ordre :

  1. devbox status affiche l'état général : accès, Podman, carte graphique, outils, environnements en cours d'installation, mises à jour. Le problème concerne une étape à faire à la main (Podman, Tailscale, la carte graphique, un iPhone) ? devbox help liste les guides pas à pas.
  2. devbox diagnostic "votre problème" lance votre agent de code sur un guide de diagnostic : il rassemble les informations, vous explique ce qui ne va pas et vous propose la correction. Il vous demande toujours votre accord avant de modifier quoi que ce soit. Par exemple : devbox diagnostic "MariaDB ne démarre pas". Sans description, il cherche tout seul ce qui cloche.
  3. Vous n'avez pas d'agent configuré, ou le problème persiste ? devbox diagnostic --report produit le même état des lieux, sans IA. Enregistrez-le dans un fichier et envoyez-le moi :
bash
devbox diagnostic --report > ~/diagnostic.txt

Le fichier se retrouve sur votre machine dans ~/dev-box/data/home/diagnostic.txt. Il ne contient aucun secret (ni token, ni clé), vous pouvez l'envoyer tel quel.

Et si vous n'arrivez même plus à vous connecter en SSH ? Depuis votre machine, cette commande vous ouvre un terminal dans la dev-box sans passer par SSH :

bash
docker exec -it -u dev dev-box zsh -l

Est-ce Open Source ? ​

Oui la dev-box est Open Source, vous pouvez retrouver le code source sur GitHub :

Comment puis-je contribuer ? ​

Vous pouvez contribuer de plusieurs manières :

  • En utilisant la dev-box et en remontant les bugs.
  • En remontant les bugs sur GitHub.
  • En proposant des améliorations sur GitHub.
  • En proposant des améliorations sur le Slack de la classe.

👋 Si vous avez des questions, n'hésitez pas.

Comment puis-je vous contacter ? ​

Vous pouvez me contacter via :

×

Reformulation

La reformulation (IA exécutée localement dans votre navigateur) peut faire des erreurs. Envisagez de vérifier les informations.