tenebrous-sheets/README.md

Tenebrous Sheets

An open source character sheet service for tabletop roleplaying games.

Currently under heavy development.

The Stack

This project makes use of these technologies:

• Rust
• Rocket Web Framework
• Tonic gRPC Framework
• Typescript

Building is backed by: cargo, npm, and webpack.

Build Instructions

These are very basic build instructions. They assume you already have cargo set up and installed.

Initial Setup

Quick initial setup instructions that will set up a development environment.

First, install dependencies by either using the command below (Void Linux), or reading the "Dependencies Required" section:

xbps-install sqlite sqlite-devel protobuf nodejs docker

Then run the required cargo commands to install management tools and create a development database:

cargo install --version=0.2.0 sqlx-cli
cargo install cargo-run-script
cargo run --bin tenebrous-migrate

Dependencies Required

Dependencies required to build the project. The exact installation method depends on your OS.

• sqlite3 and development headers (Void Linux: xbps-install sqlite sqlite-devel, Ubuntu: apt install sqlite3 libsqlite3-dev).
• protoc: protocol buffers compiler. Needed to compile protobuf files for both the server and web frontends (Void Linux: xbps-install protobuf).
• Node and npm: Needed to run webpack for compiling and injecting Typescript into various web pages (Void Linux: xbps-install nodejs).
• Docker: Needed to run the grpc proxy (Void Linux xbps-install docker).

Run Application

Command line "instructions" to build and run the application:

cargo run-script grpc-proxy # only required if proxy not already running
cargo run

The sqlite database is created in the directory cargo run was invoked from by default. You can also pass a path to a different location as a single argument to the program.

Development

Development instructions.

To set up a local database, or run migrations, run:

cargo run --bin tenebrous-migrate

Database Queries and Migrations

When adding/updating a compile-checked query or a migration, you need to update the SQLx data JSON file:

cargo sqlx prepare -- --bin tenebrous

gRPC-Web Proxy

The frontend web application makes use of the gRPC-Web protocol to call gPRC endpoints from the browser. This requires a proxy to translate the calls from the browser to HTTP2 calls gRPC understands. For development, executing the cargo run-script grpc-proxy command will start the envoy proxy recommended by Google's gRPC-Web project.

The envoy configuration assumes you are on Linux. If you are using Mac OS or Windows, see the note in the envoy configuration.