Skip to content

Installation

ROMKADE Manager is installed with Docker, the same way on macOS, Windows and Linux. Count about ten minutes the first time, most of it for installing Docker.

1. Install Docker

  1. Download Docker Desktop from the official Docker documentation, choosing your processor (Apple Silicon or Intel).
  2. Open the downloaded file and drag Docker into the Applications folder.
  3. Start Docker Desktop and wait until it says the engine is running (whale icon in the menu bar).
  4. If macOS asks whether Docker can find devices on your local network, allow it: this is what lets ROMKADE Manager reach the console.
  1. Turn on WSL 2 by following Microsoft's guide.
  2. Install Docker Desktop from the official Docker documentation, with the WSL 2 option.
  3. Restart if the installer asks, then start Docker Desktop and wait until the engine is running.
  4. If Windows Firewall asks, allow Docker on private networks.
  1. Install Docker Engine by following the page for your distribution in the official documentation.
  2. Install the Docker Compose plugin (instructions).
  3. Optional: follow the post-installation steps to use Docker without sudo. Otherwise, put sudo in front of the docker commands below.

Check in a terminal (Terminal on macOS and Linux, PowerShell on Windows): both commands must print a version number.

docker --version
docker compose version

2. Download and start ROMKADE Manager

These commands create a romkade folder, download the official compose.yaml file of the latest release into it, then start ROMKADE Manager in the background.

mkdir romkade && cd romkade
curl -fsSLO https://github.com/RomKade/romkade-manager/releases/latest/download/compose.yaml
docker compose up -d

mkdir romkade; cd romkade
curl.exe -fsSLO https://github.com/RomKade/romkade-manager/releases/latest/download/compose.yaml
docker compose up -d

The first start downloads the images (a few hundred MB). The file can be read before starting it: it describes two services, ROMKADE Manager and its search engine, and nothing else.

3. Open the interface

Open http://localhost:8765 in your browser. A notice shows the terms of use on first launch; they stay available at any time from the sidebar.

The interface only answers on this computer: this is on purpose, since it controls your console.

Next step

Connect your console.

Good to know

  • Nothing to configure: the file works as is.
  • Your data (catalog, settings, save copies, secrets) lives in the Docker volume romkade-data. It survives updates and docker compose down. See Data and privacy.
  • Automatic start: ROMKADE Manager starts again with Docker. To stop it: docker compose down in the romkade folder.

  • Port 8765 already used? Start with another port, then open that one (for example http://localhost:8780):

    ROMKADE_PORT=8780 docker compose up -d

    $env:ROMKADE_PORT=8780; docker compose up -d

Updating

In the romkade folder:

docker compose pull
docker compose up -d

The release notes are on GitHub. Your data is kept.

Useful commands

Run them in the romkade folder.

Command Effect
docker compose ps State of the services
docker compose logs -f Live logs (Ctrl+C stops following; the service keeps running)
docker compose pull Downloads the new version of the images, without restarting anything
docker compose up -d Starts, or restarts with the updated images
docker compose down Stops and removes the containers; the volumes, so your data, are kept

Never docker compose down -v out of habit

The -v option also deletes the volumes: catalog, save copies and settings would be lost.

From the source code (macOS)

For contributors, or to use the app from a phone. Requires Python 3.13 from python.org (Homebrew's Python is blocked by the macOS Local Network permission and cannot reach the console), and Node 20 or later (brew install node) to build the interface.

git clone https://github.com/RomKade/romkade-manager.git
cd romkade-manager
./run.sh

On the first run the script creates the Python environment and builds the interface (a few minutes), then starts the server and opens http://127.0.0.1:8765. Keep the Terminal window open; Ctrl+C stops the server. The first time, allow Terminal to find devices on the local network.

  • Passwords and keys go to the macOS keychain; data to ~/Library/Application Support/AnbernicGameManager/.
  • Search uses Typesense if Docker Desktop is running (container agm-typesense), otherwise a built-in search.
  • Update: git pull, then ./run.sh.