Quick Start
Prerequisites
Required
- A PC running Linux or Windows with WSL enabled (to generate the installation USB key).
- An x86_64 computer with at least one Ethernet port and a Wi-Fi card (or USB key) that will serve as the RecoveryBox.
- A screen connected to the RecoveryBox for monitoring the installation.
Optional
- A USB GPS receiver.
- An RTL-SDR compatible USB key.
Installation Steps
1. Preparing the installation media
Important
These steps must be performed in WSL or on a Linux system. Using Windows alone is not supported. This step must be performed on a different computer from the one that will be used as RecoveryBox. The target computer must boot from the generated USB key.
- Download the latest release of debian-13-preseed-RB.
- Use Rufus or Raspberry Pi Imager to create a bootable USB key from the ISO file in the zip.
2. System installation
- Connect the network cable to the Ethernet port of the future RecoveryBox.
- Boot the machine from the USB key.
- Wait until the automated Debian installation is fully complete.
- Connect the hardware peripherals:
- Wi-Fi key (if no internal Wi-Fi card is present);
- USB GPS receiver (optional);
- RTL-SDR key (optional).
3. RecoveryBox installation
- Log in:
Username: recuser
Password: Recovery
- Switch to administrator:
sudo su -
Password:
Recovery
- Create the data directory:
mkdir /data
- Clone the project repository:
git clone --branch 1.5.1 https://github.com/mr-dgidgi/RecoveryBox.git
- Launch the installation script:
cd RecoveryBox
bash install.sh
4. Installation process
The installation script automatically performs the following operations, combining the script's direct actions with those executed by the Ansible playbook it invokes:
Phase 1 — Checks and prerequisites (script)
| Step | Description |
|---|---|
| Prerequisites check | Verifies administrator rights, amd64 architecture, presence of the /data directory, and Debian system. |
| Hardware check | Checks for a Wi-Fi interface for the access point. |
| Keyboard layout | Offers to reconfigure the keyboard layout (optional). |
| Ansible installation | Installs Ansible, python3-docker, python3-apt, and Galaxy collections (community.docker). |
Phase 2 — Interactive configuration (script)
| Step | Description |
|---|---|
| Language selection | Selects the language for installed content (French, English, or both). |
| Installation mode | Choice between default or custom installation. |
| Service configuration | (custom mode) Allows enabling or disabling each service individually (Apache, Library, BRouter, TileServer, Meshtastic, Console, OpenWebRX, Kiwix). |
| Kiwix downloads | (custom mode) Configures Wikipedia FR/EN download and desired size (all_mini, all_no_pic, all_maxi). |
| Meshtastic node configuration | (custom mode) Sets the IP address and MAC of a Meshtastic node (optional). |
| HTTPS activation | (custom mode) Allows enabling HTTPS for all web services. |
| Config file generation | Writes the /etc/recoverybox/custom_config.yml file with the selected options. |
Phase 3 — Ansible playbook (automatic)
| Step | Description |
|---|---|
| System environment | Installs base packages (curl, git, wget, Realtek/IWLWifi firmware, gpsd, chrony, tippecanoe, etc.) and creates system directories. |
| Network configuration | Deploys iptables scripts, enables IPv4 routing, and configures the firewall. |
| Docker installation | Installs Docker and its dependencies. |
| GPS configuration | Configures GPSD and Chrony for time synchronization via GPS. |
| Management tools | Installs rbstatus, services-manager, network-configurator, and the service registry file. |
| Kiwix installation | Deploys the Kiwix Docker container (offline Wikipedia content server). |
| Kiwix download | Downloads Wikipedia ZIM files according to configuration (FR/EN, chosen size). |
| Wi-Fi access point | Installs and configures the recoverybox hotspot (simple-hotspot, hostapd, dnsmasq). |
| Apache2 | Installs and configures the Apache2 web server with service VirtualHosts. |
| PDF Library | Downloads survival documents matching the selected language. |
| Web Console | Deploys ShellInABox for remote administration. |
| TileServer-GL | Installs the cartography server and the Liberty map style. |
| Mapping tools | Installs Planetiler (Docker container) and the generate-map tool. |
| BRouter | Installs the routing engine and downloads routing data. |
| OpenWebRX Plus | Deploys the browser-accessible SDR interface. |
| RTL-SDR drivers | Compiles and installs the latest RTL-SDR Blog drivers. |
| Meshtastic Web Client | Deploys the Meshtastic web client (Docker container). |
| Meshtastic Daemon | Installs the Python daemon and BRouter cartography integration. |
| MkDocs | Deploys the RecoveryBox technical wiki (MkDocs Material Docker container). |
Phase 4 — Finalization (script)
| Step | Description |
|---|---|
| Map generation | Offers to download additional maps (continent/country) via generate-map. |
| Network configuration | Checks and configures network interfaces if needed (renaming, bridges, systemd-networkd). |
| Version recording | Copies the version file to /etc/recoverybox/. |
| Reboot | Requests a system reboot to apply all changes. |
5. First boot
Once the installation is complete:
- Reboot the RecoveryBox.
- Connect a computer or smartphone to the Wi-Fi access point:
SSID: recoverybox
Password: recoverybox
- Open a browser and navigate to:
http://recovery.box
The RecoveryBox is now operational.