Installation

How to install, update, and uninstall Replay Control on a Raspberry Pi running RePlayOS.

Quick Install#

curl -fsSL https://raw.githubusercontent.com/lapastillaroja/replay-control/main/install.sh | bash

No arguments needed. The installer:

• Auto-discovers your Pi on the network via mDNS
• Installs locally when run directly on the Pi (auto-detected)
• Falls back to beta if no stable release exists yet
• Downloads the latest release from GitHub and deploys over SSH

Install Methods#

Remote Install (from another computer)#

The default method. Run the one-liner above from any computer on the same network. The installer finds the Pi automatically via mDNS.

If auto-discovery doesn’t work, specify the address:

curl -fsSL https://raw.githubusercontent.com/lapastillaroja/replay-control/main/install.sh | bash -s -- --ip your-pi-ip

Tip: To find your Pi’s IP address, check your router’s connected devices list, or run hostname -I on the Pi.

If you already downloaded install.sh:

bash install.sh
bash install.sh --ip your-pi-ip

Local Install (on the Pi itself)#

When run on a RePlayOS Pi, the installer auto-detects that it’s running locally and installs without SSH:

curl -fsSL https://raw.githubusercontent.com/lapastillaroja/replay-control/main/install.sh | bash

SD Card Install (from a computer)#

Write directly to a mounted RePlayOS SD card before first boot. The app will start automatically when the Pi boots.

# Auto-detect the SD card
bash install.sh --sdcard

# Or specify the rootfs mount point
bash install.sh --sdcard /run/media/user/rootfs

The installer looks for mounted partitions with the RePlayOS signature (data partition with roms/, bios/, config/replay.cfg; boot partition with issue.txt). It needs the rootfs partition (ext4), not the data partition.

On Linux, you may need to mount the rootfs partition manually:

sudo mount /dev/sdX2 /mnt/replayos-rootfs
bash install.sh --sdcard /mnt/replayos-rootfs

Options#

Custom Password#

The default SSH password for RePlayOS is replayos. If you have changed it:

PI_PASS=mypassword bash install.sh --ip replay.local

Or with curl:

PI_PASS=mypassword curl -fsSL https://raw.githubusercontent.com/lapastillaroja/replay-control/main/install.sh | bash

Specific Version#

Install a particular release instead of the latest:

bash install.sh --version v0.2.0
bash install.sh --version beta

The environment variable REPLAY_CONTROL_VERSION also works:

REPLAY_CONTROL_VERSION=v0.2.0 bash install.sh

Pi Address via Environment Variable#

Instead of --ip, you can set the address via environment variable:

REPLAY_PI_ADDR=your-pi-ip bash install.sh

Dry Run#

Preview what the installer would do without making any changes:

bash install.sh --dry-run

Local Build Install#

Deploy a locally built binary instead of downloading a release:

# Use artifacts from the current directory
bash install.sh --local

# Use artifacts from a specific directory
bash install.sh --local /path/to/replay-control

This expects target/release/replay-control-app (or target/aarch64-unknown-linux-gnu/release/replay-control-app) and target/site/ to exist. Run ./build.sh or ./build.sh aarch64 first.

What Gets Installed#

The installer places these files on the Pi:

The service starts automatically on boot and listens on port 8080.

During installation, the installer also downloads the LaunchBox metadata database (~100 MB) to provide game descriptions, ratings, and genres out of the box. To skip this step:

bash install.sh --no-metadata

Update#

To update to the latest version, run the installer again. It overwrites the binary and site assets, restarts the service, and preserves your environment configuration.

curl -fsSL https://raw.githubusercontent.com/lapastillaroja/replay-control/main/install.sh | bash

To update to a specific version:

bash install.sh --version v0.3.0

Uninstall#

Remove the app from the Pi:

bash install.sh --uninstall

This stops and disables the service, removes the binary, site assets, systemd unit, and Avahi service file. The environment file (/etc/default/replay-control) is preserved in case you want to reinstall later.

Uninstall is only supported via SSH, not in SD card mode.

Environment Configuration#

After installation, you can customize behavior by editing /etc/default/replay-control on the Pi:

Windows Users#

Run the install commands in WSL (Windows Subsystem for Linux).

Troubleshooting#

Pi not found: Ensure the Pi is powered on and connected to the same network. Try specifying the IP directly with --ip.

SSH authentication failed: Check the password. The default is replayos. Use PI_PASS=yourpassword if you have changed it.

SD card rootfs not mounted: On Linux, the ext4 rootfs partition may not auto-mount. Use lsblk -o NAME,LABEL,FSTYPE to find the right partition and mount it manually.