Installation

Installer ROMKADE Manager avec Docker

Deux étapes : installer Docker, l'outil gratuit qui fait tourner ROMKADE Manager sur votre ordinateur, puis lancer ROMKADE Manager.

1. Installer Docker Desktop 2. Lancer ROMKADE Manager

Docker est déjà installé ? Passez directement à l'étape 2. Autre système : macOS, Windows ou Linux.

Une seule image pour macOS, Windows et Linux, processeurs Intel/AMD et ARM · version 0.4.0 du 18 octobre 2026.

English version · Versión en español

Avant de commencer

DockerDocker Desktop (macOS, Windows) ou Docker Engine + Compose (Linux).
Même réseauLa console et l'ordinateur sont sur le même réseau local.
SSH sur la consoleServeur SSH actif, identifiant et mot de passe (ou clé SSH).
Firmware compatibleVérifiez la matrice avant de commencer.

Étape préalable

Installer Docker

Téléchargez Docker Desktop depuis la documentation officielle de Docker (nouvel onglet), en choisissant la version de votre processeur (Apple Silicon ou Intel).
Ouvrez le fichier téléchargé et glissez Docker dans le dossier Applications.
Lancez Docker Desktop et attendez que le moteur indique qu'il fonctionne (icône de la baleine dans la barre des menus).
Si macOS demande l'autorisation d'accéder au réseau local, acceptez-la : c'est elle qui permet de joindre la console.

Installez Docker Engine en suivant la page de votre distribution dans la documentation officielle (nouvel onglet).
Installez le plugin Docker Compose (instructions (nouvel onglet)).
Facultatif : suivez les étapes post-installation (nouvel onglet) pour utiliser Docker sans sudo, en connaissant les implications de sécurité du groupe docker.

ROMKADE Manager

Lancer ROMKADE Manager

Quatre étapes, une dizaine de minutes la première fois.

1Vérifier Docker
Dans un terminal (Terminal sur macOS et Linux, PowerShell sur Windows), ces deux commandes doivent afficher un numéro de version :
Terminal
```
$ docker --version
$ docker compose version
```
Message « Cannot connect to the Docker daemon » ? Docker Desktop n'est pas lancé : voir les problèmes fréquents plus bas.
2Télécharger et démarrer
Version disponible : 0.4.0 du 18 octobre 2026 · nouveautés
Ces commandes créent un dossier romkade, y téléchargent le fichier compose.yaml officiel de la dernière release, puis démarrent ROMKADE Manager en arrière-plan.
macOS et Linux
```
$ mkdir romkade && cd romkade
$ curl -fsSLO https://github.com/RomKade/romkade-manager/releases/latest/download/compose.yaml
$ docker compose up -d
```
Windows (PowerShell)
```
$ mkdir romkade; cd romkade
$ curl.exe -fsSLO https://github.com/RomKade/romkade-manager/releases/latest/download/compose.yaml
$ docker compose up -d
```
Le premier démarrage télécharge les images (quelques centaines de Mo). Linux sans le groupe docker : ajoutez sudo devant docker compose. Fichier consultable avant de le lancer : compose.yaml, notes de version.
3Ouvrir l'interface
Ouvrez localhost:8765 (nouvel onglet) dans votre navigateur. L'interface n'est accessible que depuis cet ordinateur : c'est voulu, elle pilote votre console.
4Connecter la console
1. Dans Paramètres → Connexion, saisissez l'adresse IP de la console, l'utilisateur SSH et le mot de passe (ou la clé SSH).
2. Comparez l'empreinte de la clé de la console avec celle affichée par la console, puis approuvez-la. Si elle change un jour, la connexion sera bloquée.
3. Lancez Tester la connexion : six étapes sont vérifiées, avec un conseil à chaque échec.
4. Lancez la première synchronisation : la carte est lue sans rien y écrire.

Bon à savoir

Rien à configurer : le fichier fonctionne tel quel, avec le moteur de recherche Typesense inclus.
Données : catalogue, réglages, copies de sauvegardes et secrets vivent dans le volume Docker romkade-data. Ils survivent aux mises à jour et à docker compose down.
Port : 8765 par défaut. Déjà pris ? ROMKADE_PORT=8780 docker compose up -d (PowerShell : $env:ROMKADE_PORT=8780; docker compose up -d), puis ouvrez le port choisi.
Secrets : le mot de passe de la console et les clés d'API restent dans ce volume, lisibles par le seul compte du conteneur. Ne partagez pas une copie du volume.
Démarrage automatique : ROMKADE Manager redémarre avec Docker. Pour l'arrêter : docker compose down dans le dossier romkade.

Utilisateurs avancés

Commandes utiles

À lancer dans le dossier qui contient compose.yaml. Référence complète : docker compose (nouvel onglet).

Commande	Effet
`docker compose ps`	État des services : en marche, arrêtés, en redémarrage.
`docker compose logs -f`	Journaux en direct (Ctrl+C pour quitter le suivi, le service continue).
`docker compose pull`	Télécharge la nouvelle version des images, sans rien redémarrer.
`docker compose up -d`	Démarre, ou redémarre avec les images à jour. Les volumes sont conservés.
`docker compose down`	Arrête et supprime les conteneurs. Les volumes, donc vos données, sont conservés.

Jamais « docker compose down -v » par habitude

L'option -v supprime aussi les volumes : catalogue, copies de sauvegardes et réglages seraient perdus. Ne l'utilisez que pour tout effacer volontairement, après avoir copié vos données.

Mettre à jour

Lisez d'abord les notes de version, puis :

Terminal

$ docker compose pull
$ docker compose up -d

Sauvegarder et restaurer

Copie du volume de données dans une archive du dossier courant, puis restauration :

Terminal

$ docker compose down
$ docker run --rm -v romkade_romkade-data:/data -v "$PWD":/backup alpine tar czf /backup/romkade-data.tgz -C /data .
$ docker compose up -d

Restaurer : même commande avec tar xzf /backup/romkade-data.tgz -C /data, service arrêté. PowerShell : remplacez "$PWD":/backup par "${PWD}:/backup".

Désinstaller

docker compose down, puis supprimez le dossier romkade. Le volume de données reste en place tant que vous ne le supprimez pas vous-même (docker volume rm romkade_romkade-data).

Transparence

Ce que Docker ne règle pas tout seul

Un conteneur n'a pas automatiquement accès au réseau local, aux périphériques ni au trousseau de votre système. Le Bluetooth, le son et les manettes, eux, sont réglés sur la console par le réseau : l'ordinateur hôte n'a pas besoin de Bluetooth.

Besoin	Comment c'est réglé
Joindre la console sur le réseau local (SSH, commandes réseau de RetroArch)	Toutes les fonctions passent par là. Le conteneur doit pouvoir sortir vers l'adresse IP de la console.
Ranger les secrets (mot de passe de la console, clés d'API)	Dans le conteneur, un fichier secrets.json du volume de données, lisible par son seul propriétaire (le trousseau du système n'est pas accessible depuis Docker).
Recherche intelligente (moteur Typesense)	Un second service du même fichier compose.yaml, sans port publié : joignable seulement par ROMKADE Manager.
Accès depuis un téléphone	Pas avec Docker : l'interface n'est ouverte qu'à l'ordinateur hôte (127.0.0.1), par sécurité. L'accès protégé par mot de passe depuis un téléphone existe dans l'installation depuis les sources (macOS).

Testé à chaque version : parcours complet sur Linux (Intel/AMD et ARM) avec une console simulée, et sur macOS (Docker Desktop, Apple Silicon). Windows : fichier et commandes PowerShell vérifiés ; Docker Desktop pour Windows fait tourner la même image Linux. Un souci sur votre système ? Dites-le-nous.

Règles de sécurité

N'ajoutez pas --privileged, network_mode: host ni de montage de /var/run/docker.sock au fichier fourni sans raison technique précise.
N'exposez pas ROMKADE Manager sur Internet : il commande votre console. Pour un accès à distance, attendez la méthode authentifiée documentée.
Gardez votre fichier de configuration et votre répertoire de données privés.

Dépannage

Problèmes fréquents

« Cannot connect to the Docker daemon » ou « docker: command not found »

Docker Desktop n'est pas lancé (macOS, Windows) ou le service Docker est arrêté (Linux). Lancez-le et attendez que le moteur indique qu'il tourne, puis recommencez l'étape 1.

Windows : « WSL 2 installation is incomplete »

WSL 2 ou la virtualisation ne sont pas activés. Suivez le guide WSL de Microsoft (nouvel onglet), redémarrez, puis relancez Docker Desktop.

Linux : « permission denied » sur le socket Docker

Votre utilisateur n'a pas les droits sur Docker. Utilisez sudo ou suivez les étapes post-installation (nouvel onglet).

La console reste injoignable

Vérifiez que la console est allumée, connectée au même Wi-Fi et que son serveur SSH est actif. Le test de connexion des Paramètres vérifie six étapes (réseau, serveur SSH, clé de la console, identifiants, commande sur la console, dossier des ROMs) et indique celle qui échoue.

macOS : « No route to host » alors que la console répond

macOS bloque l'accès au réseau local pour l'application concernée. Ouvrez Réglages Système → Confidentialité et sécurité → Réseau local et autorisez-la.

Pour aller plus loin : Documentation complète (nouvel onglet)

Installer ROMKADE Manager avec Docker

Avant de commencer

Installer Docker

macOS

Windows

Linux

Lancer ROMKADE Manager

1Vérifier Docker

2Télécharger et démarrer

3Ouvrir l'interface

4Connecter la console

Bon à savoir

Commandes utiles

Mettre à jour

Sauvegarder et restaurer

Désinstaller

Ce que Docker ne règle pas tout seul

Problèmes fréquents