Skip to content

About

RoboMiner converted to Rust

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

521 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

RoboMiner

RoboMiner is an online programming game. Improve the program for your robot to mine more efficiently.

Prerequisites

  • Rust toolchain with Cargo.
  • A supported database: MySQL 8.4 or MariaDB 10.11+ (CI exercises MySQL 8.4 and MariaDB 11.4; connection URLs use the mysql:// scheme for both).

Arch / Omarchy

Omarchy (and other Arch Linux systems) can develop and run from source without Debian tooling:

sudo pacman -S --needed base-devel rustup nodejs npm python mariadb mariadb-clients
# Optional: Docker when you prefer containerized MySQL 8.4 instead of host MariaDB
sudo pacman -S --needed docker

Omarchy already ships rustup. Use that instead of the pacman rust package (they conflict). The Pi cross-compile scripts require rustup so they can add the aarch64-unknown-linux-gnu target. Extra packages for that path are listed under Raspberry Pi (64-bit) cross-compile.

Prefer host MariaDB on Arch and Raspberry Pi (common system package). Docker MySQL 8.4 remains a supported alternative via the test helpers. The usual test entry point reuses local MySQL/MariaDB on 127.0.0.1:3306 when the schema is present, or starts a Docker MySQL container when needed:

resources/scripts/run-tests-with-db.sh

Day-to-day builds are unchanged (cargo build --workspace). To install with systemd using an Arch package (same layout as the .deb), see deploy/arch/README.md.

The database scripts are kept under resources/database/:

  • createDatabase.sql — database schema
  • gameData.sql — seed data (ores, parts, areas, achievements)
  • balanceTestData.sql — optional offline balance-experiment seed (not loaded by init-ci-database.sh)

Further docs: CONTRIBUTING.md (tests, coverage, db vs domain boundary), docs/architecture.md (crate layers and request flows), docs/crate-map.md (module ownership), ACHIEVEMENTS.md (progression and claim flow), gameflow.md (early-game balance notes), ROBOTS.md (sample robot programs).

Build

Build every Rust crate in the workspace:

cargo build --workspace

Build optimized release binaries:

cargo build --workspace --release

Raspberry Pi (64-bit) cross-compile

From an x86_64 machine, resources/scripts/build-release.sh builds native release binaries and then cross-compiles robominer-engine / robominer-web for aarch64-unknown-linux-gnu. resources/scripts/build-deb.sh does the same and packages .deb files for a Raspberry Pi running Debian/Raspberry Pi OS.

Both scripts look for the linker binary aarch64-linux-gnu-gcc (see .cargo/config.toml). They also require rustup and will run rustup target add aarch64-unknown-linux-gnu if that target is missing.

Install the host packages first. Package names differ by distro; the linker binary name does not.

Ubuntu / Debian

sudo apt install gcc-aarch64-linux-gnu
cargo install cargo-deb --locked   # once; only needed for build-deb.sh

dpkg-deb is already present with dpkg on Ubuntu/Debian.

Omarchy / Arch

omarchy pkg add aarch64-linux-gnu-gcc dpkg
# or: sudo pacman -S --needed aarch64-linux-gnu-gcc dpkg
cargo install cargo-deb --locked   # once; only needed for build-deb.sh

aarch64-linux-gnu-gcc pulls aarch64-linux-gnu-binutils and aarch64-linux-gnu-glibc and installs the same aarch64-linux-gnu-gcc linker the scripts call. dpkg provides dpkg-deb. Confirm with command -v aarch64-linux-gnu-gcc and command -v dpkg-deb. Confirm cargo-deb with cargo deb --version (not command -v cargo-deb): Omarchy rustup does not put ~/.cargo/bin on PATH, but cargo deb still finds the plugin. Binaries-only builds (build-release.sh) need only the cross gcc, not dpkg / cargo-deb.

Then build:

resources/scripts/build-release.sh
# or, with cargo-deb + dpkg-deb installed:
resources/scripts/build-deb.sh

On a Pi that is already aarch64, the scripts skip the cross step and build natively. To install RoboMiner as an Arch package on an aarch64 Arch/Omarchy Pi, use deploy/arch/README.md (makepkg) instead of cross-building a .deb.

Install on the target host (example for a native build artifact):

sudo apt install ./target/debian/robominer_*.deb

On a Pi, copy the aarch64 .deb from the build output and install the same way. If /etc/robominer/robominer.env already exists, the package postinst runs migrate apply, applies gameData.sql, and starts the systemd units.

On Arch / Omarchy, build an installable package instead of a .deb:

cd deploy/arch
./makepkg-local.sh -si

Details and an AUR publish checklist: deploy/arch/README.md.

The main binaries are:

  • target/debug/robominer-engine
  • target/debug/robominer-web
  • target/release/robominer-engine
  • target/release/robominer-web

Test And Check

See CONTRIBUTING.md for the full test workflow, route-to-test matrix, coverage floor (93), golden fixtures, git hooks, and crate-boundary rules.

resources/scripts/run-tests-with-db.sh   # same entry point as CI (MySQL 8.4 + MariaDB)
resources/scripts/run-fast-tests.sh      # no database
cargo fmt --all -- --check
cargo clippy --workspace -- -D warnings
cargo check --workspace

Enable the repo pre-commit hook (rustfmt + Clippy when .rs files are staged):

git config core.hooksPath .githooks

Database

To initialize or refresh schema manually (createDatabase.sql then gameData.sql, then schema migrations):

resources/scripts/init-ci-database.sh
ROBOMINER_FORCE_DB_REINIT=1 resources/scripts/init-ci-database.sh

Apply pending schema migrations to an existing database (also auto-baselines a schema that already matches createDatabase.sql):

resources/scripts/migrate-database.sh
# or:
cargo run -p robominer-engine -- migrate apply
cargo run -p robominer-engine -- migrate status
cargo run -p robominer-engine -- migrate status --check

migrate status --check exits non-zero while migrations are pending. The web host exposes loopback readiness at GET /health (database ping + migration currency).

Backup and restore

Create a full logical dump (password is passed via MYSQL_PWD, not argv):

resources/scripts/backup-database.sh
# or:
resources/scripts/backup-database.sh /path/to/backup.sql.gz

Restore a dump (forward-only migrations — rollback means restore a pre-change backup and matching binaries):

resources/scripts/restore-database.sh /path/to/backup.sql.gz
robominer-engine migrate status --check
# Confirm readiness: GET /health/ready (or GET /health)

Prefer robominer-engine migrate apply for day-to-day schema upgrades. The shell resources/scripts/migrate-database.sh remains a bootstrap/fallback path.

Versioned SQL lives under resources/database/migrations/ (NNN_description.sql). run-tests-with-db.sh resolves MySQL via an existing URL, local schema, or a persistent Docker container—details in CONTRIBUTING.md.

Run The Engine

robominer-engine is the Rust command-line replacement for the legacy native engine. It accepts the database connection in this order:

  1. Pass --database-url.
  2. Set ROBOMINER_DATABASE_URL (for example via /etc/robominer/robominer.env).

Example with an explicit database URL:

cargo run -p robominer-engine -- \
  --database-url mysql://robominer:password@localhost/RoboMiner \
  mining queue-page-states --user-id 1

Example using the environment variable:

ROBOMINER_DATABASE_URL=mysql://robominer:password@localhost/RoboMiner \
  cargo run -p robominer-engine -- leaderboard states --max-entries 10

Run the rally worker loop (--persist also credits finished mining runs into player wallets after each poll cycle). Adaptive sleep uses min(next rally claim, next wallet claim) so wallet credits are not delayed when mining finishes but no rally is due. For single-worker deploys, rally rallies --persist covers wallet claims without a separate mining claim-all --loop:

ROBOMINER_DATABASE_URL=mysql://robominer:password@localhost/RoboMiner \
  cargo run -p robominer-engine -- rally rallies --loop --sleep-seconds 5 --persist

Show all available engine commands:

cargo run -p robominer-engine -- --help

Offline tooling

robominer-optimize is an offline genetic-programming optimizer for experimenting with robot programs against the live database schema. It is not part of the production web/engine path:

cargo run -p robominer-optimize -- --help

Run The Rust Web Host

robominer-web is the Rust web host for RoboMiner. It owns the application routes, renders the remaining browser behavior from Rust source, and serves CSS from robominer-web/static.

It handles /help, /helpTutorial, /helpProgramTips, /helpRobotProgram, /helpMechanics, /logoff, /leaderboard, /miningAreaOverview, /activity, /miningQueue, /miningResults, /account, /achievements, /editCode, /login, /robot, /robotStats, and /shop.

Run it on the default address, 127.0.0.1:8080:

cargo run -p robominer-web

Or with a systemd-style env file already exported:

set -a && source /etc/robominer/robominer.env && set +a
cargo run -p robominer-web

The web host accepts the database connection in this order:

  1. Pass --database-url.
  2. Set ROBOMINER_DATABASE_URL.

Override host, port, or static asset root:

HOST=0.0.0.0 PORT=8080 ROBOMINER_WEB_ROOT=robominer-web/static cargo run -p robominer-web

Set ROBOMINER_DATABASE_URL to enable database-backed pages such as /leaderboard, /miningAreaOverview, /activity, /miningQueue, /miningResults, /account, /achievements, /editCode, /login, /robot, /robotStats, and /shop:

ROBOMINER_DATABASE_URL=mysql://robominer:password@localhost/RoboMiner cargo run -p robominer-web

Set ROBOMINER_SESSION_SECRET to sign login session cookies. When binding to 127.0.0.1, localhost, or ::1, the web host allows an insecure development default if no secret is configured. Any other bind address requires a secret and the process exits on startup if one is missing. Use a long random value in any shared or production deployment:

ROBOMINER_SESSION_SECRET="$(openssl rand -hex 32)" \
ROBOMINER_DATABASE_URL=mysql://robominer:password@localhost/RoboMiner \
cargo run -p robominer-web

Public self-registration is off by default. For local development, set ROBOMINER_ALLOW_SIGNUP=1; otherwise create users with robominer-engine user create.

Logged-in users are identified by a signed session cookie minted at login (__Host-robominer_session when Secure cookies are on; robominer_session for local loopback HTTP). The legacy plain robominer_user_id cookie is no longer accepted.

New users receive Argon2id password hashes. Legacy sha256: password hashes are no longer accepted.

Logged-off sessions are invalidated server-side: POST /logoff bumps User.sessionVersion so stolen cookies stop working. The account page also offers Log out all devices (bumps the version and reissues the current cookie).

Install the engine and web host for production with:

deploy/systemd/install-robominer.sh --migrate --enable

Or install from a Debian package built with resources/scripts/build-deb.sh:

sudo apt install ./target/debian/robominer_*.deb

Omit --migrate only if you will apply schema changes yourself afterward (robominer-engine migrate apply). The install script prints a reminder when it skips that step. The .deb postinst migrates and reloads gameData.sql automatically when /etc/robominer/robominer.env is already present.

For HTTPS, put Caddy or nginx in front of the web host. See deploy/reverse-proxy/README.md for example configs and deploy/INTERNET-HARDENING.md for firewall, rate limits, and invite-only signup (public registration is off by default; set allowsignup 1 to open it). Bind robominer-web to 127.0.0.1, set sessionsecret, and enable securecookies 1 when users reach the site over HTTPS.

See deploy/systemd/README.md for /etc/robominer/robominer.env. Environment variables are listed in docs/configuration.md.

Then open:

http://127.0.0.1:8080/login

License

RoboMiner is licensed under either of

at your option.

About

RoboMiner converted to Rust

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages