RoboMiner is an online programming game. Improve the program for your robot to mine more efficiently.
- 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).
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 dockerOmarchy 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.shDay-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 schemagameData.sql— seed data (ores, parts, areas, achievements)balanceTestData.sql— optional offline balance-experiment seed (not loaded byinit-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 every Rust crate in the workspace:
cargo build --workspaceBuild optimized release binaries:
cargo build --workspace --releaseFrom 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.shdpkg-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.shaarch64-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.shOn 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_*.debOn 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 -siDetails and an AUR publish checklist: deploy/arch/README.md.
The main binaries are:
target/debug/robominer-enginetarget/debug/robominer-webtarget/release/robominer-enginetarget/release/robominer-web
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 --workspaceEnable the repo pre-commit hook (rustfmt + Clippy when .rs files are staged):
git config core.hooksPath .githooksTo 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.shApply 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 --checkmigrate status --check exits non-zero while migrations are pending. The web host
exposes loopback readiness at GET /health (database ping + migration currency).
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.gzRestore 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.
robominer-engine is the Rust command-line replacement for the legacy native
engine. It accepts the database connection in this order:
- Pass
--database-url. - 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 1Example using the environment variable:
ROBOMINER_DATABASE_URL=mysql://robominer:password@localhost/RoboMiner \
cargo run -p robominer-engine -- leaderboard states --max-entries 10Run 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 --persistShow all available engine commands:
cargo run -p robominer-engine -- --helprobominer-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 -- --helprobominer-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-webOr with a systemd-style env file already exported:
set -a && source /etc/robominer/robominer.env && set +a
cargo run -p robominer-webThe web host accepts the database connection in this order:
- Pass
--database-url. - 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-webSet 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-webSet 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-webPublic 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 --enableOr install from a Debian package built with resources/scripts/build-deb.sh:
sudo apt install ./target/debian/robominer_*.debOmit --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
RoboMiner is licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.