summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--rust/.gitignore1
-rw-r--r--rust/README.md38
-rw-r--r--rust/env.example6
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="