Instalación

Instalar ROMKADE Manager con Docker

Dos pasos: instalar Docker, la herramienta gratuita que ejecuta ROMKADE Manager en tu ordenador, y luego iniciar ROMKADE Manager.

1. Instalar Docker Desktop 2. Iniciar ROMKADE Manager

¿Docker ya está instalado? Pasa directamente al paso 2. Otro sistema: macOS, Windows o Linux.

Una sola imagen para macOS, Windows y Linux, procesadores Intel/AMD y ARM · versión 0.4.0 del 18 de octubre de 2026.

Version française (versión de referencia) · English version

Antes de empezar

  • DockerDocker Desktop (macOS, Windows) o Docker Engine + Compose (Linux).
  • Misma redLa consola y el ordenador están en la misma red local.
  • SSH en la consolaServidor SSH activo, usuario y contraseña (o clave SSH).
  • Firmware compatibleConsulta la matriz antes de empezar.
Paso previo

Instalar Docker

  1. Descarga Docker Desktop desde la documentación oficial de Docker, eligiendo la versión de tu procesador (Apple Silicon o Intel).
  2. Abre el archivo descargado y arrastra Docker a la carpeta Aplicaciones.
  3. Inicia Docker Desktop y espera a que el motor indique que funciona (icono de la ballena en la barra de menús).
  4. Si macOS pide permiso para acceder a la red local, acéptalo: es lo que permite llegar a la consola.
ROMKADE Manager

Iniciar ROMKADE Manager

Cuatro pasos, unos diez minutos la primera vez.

  1. 1Comprobar Docker

    En un terminal (Terminal en macOS y Linux, PowerShell en Windows), estos dos comandos deben mostrar un número de versión:

    Terminal
    docker --version
docker compose version

    ¿Mensaje «Cannot connect to the Docker daemon»? Docker Desktop no está iniciado: consulta los problemas frecuentes más abajo.

  2. 2Descargar e iniciar

    Versión disponible: 0.4.0 del 18 de octubre de 2026 · novedades

    Estos comandos crean una carpeta romkade, descargan en ella el archivo oficial compose.yaml de la última versión y luego inician ROMKADE Manager en segundo plano.

    macOS y 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

    El primer inicio descarga las imágenes (unos cientos de MB). Linux sin el grupo docker: añade sudo delante de docker compose. Puedes consultar el archivo antes de ejecutarlo: compose.yaml, notas de versión.

  3. 3Abrir la interfaz

    Abre localhost:8765 en tu navegador. La interfaz solo es accesible desde este ordenador: es a propósito, controla tu consola.

  4. 4Conectar la consola

    1. En Ajustes → Conexión, escribe la dirección IP de la consola, el usuario SSH y la contraseña (o la clave SSH).
    2. Compara la huella de la clave de la consola con la que muestra la consola y apruébala. Si algún día cambia, la conexión quedará bloqueada.
    3. Ejecuta Probar la conexión: se comprueban seis pasos, con un consejo para cada fallo.
    4. Ejecuta la primera sincronización: la tarjeta se lee sin escribir nada en ella.

Conviene saber

  • Nada que configurar: el archivo funciona tal cual, con el motor de búsqueda Typesense incluido.
  • Datos: catálogo, ajustes, copias de partidas guardadas y secretos viven en el volumen Docker romkade-data. Sobreviven a las actualizaciones y a docker compose down.
  • Puerto: 8765 por defecto. ¿Ya está ocupado? ROMKADE_PORT=8780 docker compose up -d (PowerShell: $env:ROMKADE_PORT=8780; docker compose up -d) y luego abre el puerto elegido.
  • Secretos: la contraseña de la consola y las claves de API se quedan en este volumen, legibles solo por la cuenta del contenedor. No compartas una copia del volumen.
  • Inicio automático: ROMKADE Manager se reinicia con Docker. Para detenerlo: docker compose down en la carpeta romkade.
Usuarios avanzados

Comandos útiles

Ejecútalos en la carpeta que contiene compose.yaml. Referencia completa: docker compose.

ComandoEfecto
docker compose psEstado de los servicios: en marcha, detenidos, reiniciándose.
docker compose logs -fRegistros en directo (Ctrl+C deja de seguirlos, el servicio continúa).
docker compose pullDescarga la nueva versión de las imágenes, sin reiniciar nada.
docker compose up -dInicia, o reinicia con las imágenes actualizadas. Los volúmenes se conservan.
docker compose downDetiene y elimina los contenedores. Los volúmenes, y por tanto tus datos, se conservan.
Nunca «docker compose down -v» por costumbre

La opción -v también elimina los volúmenes: se perderían el catálogo, las copias de partidas guardadas y los ajustes. Úsala solo para borrarlo todo a propósito, después de copiar tus datos.

Actualizar

Lee primero las notas de versión y luego:

Terminal
docker compose pull
docker compose up -d

Hacer una copia y restaurar

Copia del volumen de datos en un archivo de la carpeta actual y luego restauración:

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

Restaurar: el mismo comando con tar xzf /backup/romkade-data.tgz -C /data, con el servicio detenido. PowerShell: sustituye "$PWD":/backup por "${PWD}:/backup".

Desinstalar

docker compose down y luego elimina la carpeta romkade. El volumen de datos se queda mientras no lo elimines tú mismo (docker volume rm romkade_romkade-data).

Transparencia

Lo que Docker no resuelve por sí solo

Un contenedor no tiene acceso automático a la red local, a los periféricos ni al llavero de tu sistema. El Bluetooth, el sonido y los mandos se configuran en la consola a través de la red: el ordenador anfitrión no necesita Bluetooth.

NecesidadCómo se resuelve
Llegar a la consola en la red local (SSH, comandos de red de RetroArch)Todas las funciones pasan por ahí. El contenedor debe poder salir hacia la dirección IP de la consola.
Guardar los secretos (contraseña de la consola, claves de API)En el contenedor, un archivo secrets.json del volumen de datos, legible solo por su propietario (el llavero del sistema no es accesible desde Docker).
Búsqueda inteligente (motor Typesense)Un segundo servicio del mismo archivo compose.yaml, sin puerto publicado: solo ROMKADE Manager puede llegar a él.
Acceso desde un teléfonoNo con Docker: la interfaz solo está abierta al ordenador anfitrión (127.0.0.1), por seguridad. El acceso protegido con contraseña desde un teléfono existe en la instalación desde el código fuente (macOS).

Probado en cada versión: recorrido completo en Linux (Intel/AMD y ARM) con una consola simulada, y en macOS (Docker Desktop, Apple Silicon). Windows: archivo y comandos de PowerShell verificados; Docker Desktop para Windows ejecuta la misma imagen Linux. ¿Algún problema en tu sistema? Cuéntanoslo.

Reglas de seguridad
  • No añadas --privileged, network_mode: host ni un montaje de /var/run/docker.sock al archivo proporcionado sin una razón técnica precisa.
  • No expongas ROMKADE Manager en Internet: controla tu consola. Para el acceso remoto, espera al método autenticado documentado.
  • Mantén privados tu archivo de configuración y tu carpeta de datos.
Solución de problemas

Problemas frecuentes

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

Docker Desktop no está iniciado (macOS, Windows) o el servicio Docker está detenido (Linux). Inícialo, espera a que el motor indique que funciona y repite el paso 1.

Windows: «WSL 2 installation is incomplete»

WSL 2 o la virtualización no están activados. Sigue la guía de WSL de Microsoft, reinicia y vuelve a iniciar Docker Desktop.

Linux: «permission denied» en el socket de Docker

Tu usuario no tiene permisos sobre Docker. Usa sudo o sigue los pasos posteriores a la instalación.

La consola sigue sin responder

Comprueba que la consola está encendida, conectada a la misma red Wi-Fi y que su servidor SSH está activo. La prueba de conexión de los Ajustes comprueba seis pasos (red, servidor SSH, clave de la consola, credenciales, comando en la consola, carpeta de ROMs) e indica cuál falla.

macOS: «No route to host» aunque la consola responde

macOS bloquea el acceso a la red local para la aplicación en cuestión. Abre Ajustes del Sistema → Privacidad y seguridad → Red local y autorízala.

Para ir más lejos: Documentación completa