tenebrous-sheets/README.md

105 lines
2.7 KiB
Markdown
Raw Normal View History

2020-12-09 21:45:56 +00:00
# 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.
2020-12-09 21:45:56 +00:00
## Build Instructions
These are very basic build instructions. They assume you already have
2020-12-31 14:09:01 +00:00
cargo set up and installed.
2020-12-09 21:45:56 +00:00
### Initial Setup
2020-12-09 21:45:56 +00:00
Quick initial setup instructions that will set up a development
environment.
2020-12-09 21:45:56 +00:00
First, install dependencies by either using the command below (Void
Linux), or reading the "Dependencies Required" section:
2020-12-09 21:45:56 +00:00
```
xbps-install sqlite sqlite-devel protobuf nodejs docker
```
2020-12-31 14:09:01 +00:00
Then run the required `cargo` commands to install management tools and
create a development database:
2020-12-09 21:45:56 +00:00
```
2020-12-31 14:09:01 +00:00
cargo install --version=0.2.0 sqlx-cli
cargo install cargo-run-script
2020-12-31 14:09:01 +00:00
cargo run --bin tenebrous-migrate
2020-12-09 21:45:56 +00:00
```
### 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`).
2020-12-09 21:45:56 +00:00
### Run Application
2020-12-09 21:45:56 +00:00
Command line "instructions" to build and run the application:
```
cargo run-script grpc-proxy # only required if proxy not already running
2020-12-09 21:45:56 +00:00
cargo run
```
2020-12-31 14:09:01 +00:00
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
```
2020-12-09 21:45:56 +00:00
### 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.
2020-12-09 21:45:56 +00:00
[rustup]: https://rust-lang.github.io/rustup/index.html