¶ Introduction

RoninOS is customized to provide a "plug & play" experience for RoninDojo bitcoin nodes. This repository contains scripts for building RoninOS, which is possible thanks to the Armbian Build project. Follow the detailed instructions for regular users and developers.

¶ RoninOS - Build Using x86

The following docker image build process has been tested using Debian 12 (bookworm) and Ubuntu 24.04 (noble). Testing includes standard x86 based deployments and virtual machines. Thanks to qemu-user-static, which is used for the execution of binaries compiled for different architectures, it is possible to build Armbian images for ARM architecture while using an x86 machine.

¶ Docker Build Instructions:

1. Boot up Debian, Ubuntu, Windows Subsystem Linux, or try using an x86 Virtual Machine. Suggested resources for your machine (or virtual machine) is 8GB RAM and 50GB storage or greater.

2. Open terminal then run all commands below to install git, tor, and clone RoninOS repository over tor.

sudo apt-get update && sudo apt-get install git tor
git config --global --unset http.proxy
git config --global http.proxy socks5h://127.0.0.1
git clone http://2l2o5umijiwxjioxwpsvwxe6pr75tj7r5rggnl5ze256guwvtee3kpqd.onion/Ronin/RoninOS.git

3. Change to the RoninOS directory.

cd /$HOME/RoninOS/

4. Run the build using any of the following options. On first run, you will be asked to reboot to apply changes first.

./build-roninos.sh rockpro64
./build-roninos.sh rock-5b-plus
./build-roninos.sh rpi4b

¶ RoninOS - Build Using ARM

The following native image build process has been tested using Armbian. Testing includes a standard deployment on Rockpro64 and Rock5B. Docker is diabled for native builds by scripts which set the variable BUILD_DOCKER=no.

¶ Native Build Instructions:

1. Boot up Armbian on a Rockpro64 or Rock5B. Suggested resources is 50GB storage or greater.

2. Open terminal then run all commands below to install git, tor, and clone RoninOS repository over tor.

sudo apt-get update && sudo apt-get install git tor
git config --global --unset http.proxy
git config --global http.proxy socks5h://127.0.0.1
git clone http://2l2o5umijiwxjioxwpsvwxe6pr75tj7r5rggnl5ze256guwvtee3kpqd.onion/Ronin/RoninOS.git

3. Change to the RoninOS directory.

cd /$HOME/RoninOS/

4. Run the build using any of the following options. On first run, you will be asked to reboot to apply changes first.

./build-roninos.sh rockpro64
./build-roninos.sh rock-5b-plus
./build-roninos.sh rpi4b

¶ x86 Virtual Machines

It is useful to build RoninOS using x86 virtual machines rather than use other environments. This method is faster than native builds using ARM computers, and leaves your other x86 work enviorments clean. Here are some tips to setting up virtual machines which can be used to build RoninOS images.

¶ Mac & Windows

Installing Ubuntu Virtual Machine

1. Go to VirtualBox website and download for macOS or Windows.

2. Go to the Ubuntu website and download Ubuntu ISO.

3. Open VirtualBox and create a new virtual machine, set the type to "Linux" and version to Ubuntu 64bit.

4. Allocate 8GB RAM and 50GB storage.

5. Start the virtual machine and select the Ubuntu ISO file downloaded earlier.

6. Install Ubuntu and finish the setup wizard.

7. After setup update and reboot.

sudo apt update && sudo apt upgrade -y
sudo reboot

¶ Linux

...

¶ Development

The following section is for developers and advanced users only.

¶ RoninOS - Developer Build

The developer build information covers building an image using the develop branch, helpful commands, file structure, and other notes relevant to development deployments of RoninOS.

¶ Developer Build Instructions

1. Run the build using any of the following options. On first run, you will be asked to reboot to apply changes first.

Usage:
./build-roninos.sh <board> [develop]

Examples:
./build-roninos.sh rockpro64
./build-roninos.sh rock-5b-plus
./build-roninos.sh rpi4b

./build-roninos.sh rockpro64 develop
./build-roninos.sh rock-5b-plus develop
./build-roninos.sh rpi4b develop

2. Clone, fetch, and checkout the RoninOS develop branch.

sudo apt-get update && sudo apt-get install git tor
git config --global --unset http.proxy
git config --global http.proxy socks5h://127.0.0.1
git clone http://2l2o5umijiwxjioxwpsvwxe6pr75tj7r5rggnl5ze256guwvtee3kpqd.onion/Ronin/RoninOS.git
cd /$HOME/RoninOS/ && git fetch && git checkout develop

3. Edit the defaults.sh script if you prefer to modify variables.

nano /$HOME/RoninOS/defaults.sh

4. Edit build-roninos.sh to set a different WORKING_DIR= if preferred.

nano /$HOME/RoninOS/build-roninos.sh

5. Check logs for "plug & play" image.

tail -f /home/ronindojo/.logs/setup.logs

6. The following error can be safely ignored in setup.logs file. It occurs during RoninUI setup because the dev created the tar package on MacOS, which adds custom flags that Linux tar doesn't recognize.

tar: Ignoring unknown extended header keyword 'LIBARCHIVE.xattr.com.apple.provenance'

7. Start or stop ronin-setup service.

sudo systemctl start ronin-setup
sudo systemctl stop ronin-setup

¶ File Structure:

Take note that all repo links are .onion so have Tor Browser ready.

• build-roninos.sh - Begin the RoninOS image compiling process. The WORKING_DIR= variable in this script is where all work will be done.

• customize-image.sh - Script used as a hook to customize the image at the end of the building process. Including setting username, password (random password), cloning repositories, modifying tor, and preparing the user interface.

• defaults.sh - Contains the set defaults for build options, branches, repositories, etc. Modify variables if preferred.

• functions.sh - Contains all functions for build script.

• sign-roninos.sh - Script used to sign images with PGP key.

¶ Developer Format:

Ready to contribute to the RoninDojo project? Please read these reminders before submitting a PR.

1. Try to stay POSIX compliant! POSIX compliance indicates that an operating system follows a set of standards making it compatible with other systems and supporting a consistent programming interface.

2. Use spaces not tabs.

3. All variables that are meant to be global or constant should upper case, and all local variables within scripts should be lowercase. This will improve readability and eliminate confusion between local and global variables.

VARIABLE=test   #global
variable=test   #local

4. All function names should have leading underscores _. If additional spacers are needed always use underscores _ rather than dashes - or any other spacer. For example a function with the purpose of printing an informational message in the terminal would be named _print_message(). This will help with telling the difference between commands and functions.

5. All script names should have dashes - if needed, rather than underscores _, or any other spacer. For example a script with the purpose of setting defaults via variables would be named defaults-dojo.sh.

6. All scripts should be stored in their respective directory and named appropriately. For example a script related to data backup functions named functions-backup.sh should be stored in the directory /$HOME/ronindojo/scripts/functions/.

7. All file paths should be in lower case unless impossible because of something like upstream. For example the file path for the Dojo install script is /$HOME/ronindojo/scripts/install/install-dojo.sh.

8. Use the print message function named _print_message() rather than echo commands if printing informational messages in the terminal.

9. All URLs should be lower case.

https://repo.onion/ronin/dojo.git
https://repo.onion/ronin/ronindojo.git
https://repo.onion/ronin/roninui.git
https://repo.onion/ronin/roninos.git

¶ Developer Resources:

• https://docs.armbian.com/Developer-Guide_Build-Preparation

• https://github.com/armbian/build

• https://docs.docker.com/engine/install