diff options
| -rw-r--r-- | rust/.gitignore | 1 | ||||
| -rw-r--r-- | rust/README.md | 38 | ||||
| -rw-r--r-- | rust/env.example | 6 |
3 files changed, 36 insertions, 9 deletions
diff --git a/rust/.gitignore b/rust/.gitignore index 18b70ae0..a2068a8a 100644 --- a/rust/.gitignore +++ b/rust/.gitignore @@ -1,3 +1,4 @@ +.env target/ !.cargo diff --git a/rust/README.md b/rust/README.md index ecbfba2d..a6bb34b6 100644 --- a/rust/README.md +++ b/rust/README.md @@ -3,25 +3,24 @@ Rust implementation of fatcat API server (`fatcatd`). ## Development +You need the following dependencies installed locally to build, run tests, and +do development work: + - rust stable, 1.29+ (eg, via "rustup", includes cargo tool) - diesel (`cargo install diesel_cli`) - postgres (9.6+; targetting 11.1 for production) - postgres libs (debian: `sudo apt install libsqlite3-dev libpq-dev`) - libsodium library and development headers (debian: `libsodium-dev`) +Copying commands out of `../.gitlab-ci.yml` file may be the fastest way to get +started. + Create a new postgres superuser. A regular postgres user and an existing database should also work (with up/down migrations), but it's easier to just blow the entire database away. -Create a `.env` file with configuration: - - DATABASE_URL=postgres://fatcat:tactaf@localhost/fatcat_rs - TEST_DATABASE_URL=postgres://fatcat:tactaf@localhost/fatcat_rs_test - AUTH_LOCATION=dev.fatcat.wiki - AUTH_KEY_IDENT=2018-12-31-dev - AUTH_SECRET_KEY=VQe8kdn8laZ3MArKAzOeWWNUQgM6IjduG2jwKnSWehQ= - -Re-create database from scratch: +Copy `env.example` to `.env`, update if needed, then re-create database from +scratch: diesel database reset @@ -34,3 +33,24 @@ Tests: cargo test -- --test-threads 1 See `HACKING` for some more advanced tips and commands. + +## Configuration + +All configuration goes through environment variables, the notable ones being: + +- `DATABASE_URL`: postgres connection details (username, password, host, and database) +- `TEST_DATABASE_URL`: used when running `cargo test` +- `AUTH_LOCATION`: the domain authentication tokens should be valid over +- `AUTH_KEY_IDENT`: a unique name for the primary auth signing key (used to + find the correct key after key rotation has occured) +- `AUTH_SECRET_KEY`: base64-encoded secret key used to both sign and verify + authentication tokens (symmetric encryption) +- `AUTH_ALT_KEYS`: additional ident/key pairs that can be used to verify tokens + (to enable key rotation). Syntax is like `<ident1>:<key1>,<ident2>:key2,...`. + +To setup authentication with a new secret authentication key, run: + + cargo run --bin fatcat-auth create-key + +then copy the last line as `AUTH_SECRET_KEY` in `.env`, and update +`AUTH_KEY_IDENT` with a unique name for this new key (eg, including the date). diff --git a/rust/env.example b/rust/env.example new file mode 100644 index 00000000..0ecf58a5 --- /dev/null +++ b/rust/env.example @@ -0,0 +1,6 @@ +DATABASE_URL="postgres://fatcat:tactaf@localhost/fatcat" +TEST_DATABASE_URL="postgres://fatcat:tactaf@localhost/fatcat_test +AUTH_LOCATION="dev.fatcat.wiki" +AUTH_KEY_IDENT="20190101-dev-dummy-key" +AUTH_SECRET_KEY="5555555555555555555555555555555555555555555=" +AUTH_ALT_KEYS="20181220-dev:6666666666666666666666666666666666666666666=,20181210-dev:7777777777777777777777777777777777777777777=" |