Linux installer and Runner

Documentation · Português · macOS · Windows

Install, configure, then run

The 0.2.1 package refreshed on 13 October 2026 includes these launchers. They are also included in complete archives generated by build_release.py. For an existing 0.2.1 installation, follow the same-version reinstall instructions below.

1. Use a complete source checkout or newly generated ZIP containing Install Linux.sh. Put it in a writable local folder; keep all project files together. Use Linux x64 or ARM64 and a modern WebGL browser.

2. Open a terminal in that folder and run:

   bashCopy

   bash "./Install Linux.sh"

3. The installer detects the distribution, reuses verified local tools, downloads missing tools inside the extracted folder, installs locked Python/npm dependencies and prepares the frontend. Answer the configuration questions. Enter keeps the displayed value; Ctrl+C cancels without saving the answers.

4. The installer prepares the database and generates Gravewright Runner.sh beside itself, then exits without starting the server. Start it with:

   bashCopy

   bash "./Gravewright Runner.sh"

5. Open http://127.0.0.1:3000 and create the first owner account. Keep the terminal open while playing; Ctrl+C stops the application. Closing the browser does not stop the server. A file manager that supports “Run in Terminal” can open the executable shell files directly.

Run the installer again to change saved settings, repair missing dependencies or prepare updated/moved project files. The generated Runner uses the prepared environment and never installs tools, runs npm or asks installation questions. Paths with spaces and Unicode are supported; quote filenames in terminal commands.

Distribution and tool requirements

The Bash installer reads /etc/os-release, matching both ID and ID_LIKE. It recognizes these package-manager families when basic download/extraction prerequisites are missing:

Recognizing a family is not a claim that every release has been tested. The official private Node.js binaries need glibc 2.28+ and Linux kernel 4.18+ on x64/ARM64, as documented in Node.js 24's platform requirements. On Alpine/musl, place native Node.js 22/24 and npm 10+ in data/runner/node/native first (bin/node and lib/node_modules/npm); the installer does not substitute a glibc Node binary. Unsupported architectures or incompatible tools produce a diagnostic instead of a global tool installation.

Basic requirements are Bash 3.2+, HTTPS-capable curl, CA certificates, tar/gzip and SHA-256 verification (sha256sum or shasum). Minimal Alpine installations may need Bash installed before the entrypoint can run. Missing distribution prerequisites can require the package manager and sudo; run Gravewright itself as your regular user. An unrecognized ID/ID_LIKE stops the installer before prerequisite preparation, even if tools are present. Report those identifiers so the family can be supported, or use the manual terminal workflow.

Internet is required for missing tools and packages. Verified tools are reused from this installation; tools in another OS profile are not selected. Private tools, Python environments and caches stay in the Runner directory. The installer does not change shell profiles or the permanent PATH, and does not require Docker, Homebrew or Redis. Python preparation uses uv sync --locked --no-dev; frontend preparation uses npm ci --include=dev --include=optional and npm run build when hashes indicate work is needed. It preserves a developer .venv and source lock files. Existing frontend outputs are reused when inputs and outputs are unchanged.

Configuration and storage

Configuration is saved in the project's .env, next to the installer. Missing options are filled from .env.example; existing secrets, unrelated settings and saved answers are preserved. The installer asks for table name, language, local port, module folder, join codes, snapshots, campaign exports and tunnel access. Relative database/media/module paths start at the project root. Selecting pt-BR installs and activates the signed official Translator; a verified installed package can be reused offline. The official Marketplace is configured automatically when no catalog is configured. Existing custom catalogs are preserved, and verified official settings are reused offline. Unattended --check does not configure it.

--data-dir chooses Runner state, not the database or uploads. Change .env to relocate those. GRAVEWRIGHT_RUNNER_ROOT can select an absolute private-tool directory before running the installer; it is useful for isolated checks and does not change HOME. Prepared environments and frontend state are separated by source location, so moving a project requires rerunning the installer.

Local execution and updates

The Runner listens only on 127.0.0.1, with one server process and in-memory Channels. Debug remains off and host/origin, CSRF, sessions and campaign permissions remain active. --no-browser prints the address without opening a browser. For LAN/public HTTPS hosting, use deployment; the local launcher does not configure a public server. The tunnel option permits a separately managed local tunnel agent; the Runner does not install tunnel software.

Stop the Runner before reconfiguring or backing up. Preserve the configured database, private media and project .env together, plus Runner state for update recovery. Migrations can prevent older code from opening a newer database. Supported managed updates replace project files and regenerate the platform launcher; .runner-launchers keeps the executing launcher separate from replacement files. For manual updates, extract/checkout the complete new project and rerun its installer before starting. See deployment and rollback.

Reinstall the refreshed 0.2.1 package

The 13 October 2026 refresh keeps version 0.2.1, channel stable, Alpha stage and Gravewright-0.2.1-django.zip unchanged. A host already on 0.2.1 will not be offered an automatic update to that same version. Download the refreshed ZIP and its matching SHA-256 file; an earlier checksum belongs to the earlier archive.

Stop the Runner and back up .env, the configured database/media/module paths and Runner state. Replace application files from the complete refreshed archive in the existing project folder, preserving configuration and data. Run bash "./Install Linux.sh" again, then use its regenerated Runner. Do not replace the installation with only the shell entrypoint: its supporting scripts are part of the update. If you move the project, preserve storage paths and rerun installation in the new location.

POSIX SIGHUP is handled as an orderly stop, like terminal shutdown; it does not bypass supervisor cleanup. Interrupted update transactions are recovered on the next start. Preserve .runner-launchers/ and updates/ with Runner state. See the bilingual 0.2.1 refresh notes.

Checks and troubleshooting

Unattended preparation, without configuration questions or server startup:

bash "./Install Linux.sh" --check --no-pause --data-dir "data/check"
bash "./Gravewright Runner.sh" --check --no-browser --data-dir "data/check"

These checks write files: installation prepares tools/dependencies/frontend, .env, database and Runner; Runner --check can run migrations and collect static assets. They are not read-only. Use a disposable source copy and explicit directories for experiments. Installer flags are --check, --data-dir PATH, --port NUMBER, --no-browser, --no-pause and --help. Runner flags are --check, --data-dir PATH, --port NUMBER and --no-browser; a port override applies only to that run.

After one successful installation, unchanged tools/packages/assets can be reused with UV_OFFLINE=1 and npm_config_offline=true. This is not a promise that a fresh installation or changed dependencies work offline. See uv's offline setting.

POSIX smoke tests exercise a disposable source copy, private tools, paths with spaces/Unicode, unattended preparation, offline reuse, real HTTP readiness and graceful shutdown. The POSIX Runner workflow runs the native checks on Linux and macOS; mocked distribution tests separately cover detection branches. Platform CI does not imply every recognized distribution was tested.

All paths in the storage table are relative to the extracted project. data/runner/tmp/ holds bootstrap temporary files. Explicit relative state/tool overrides resolve from this project, never from the caller's working directory.