mirror of
https://github.com/mozilla-services/syncstorage-rs.git
synced 2026-05-05 20:26:26 +02:00
docs: adjust PR template, finish combining READMEs
adding makefile with example ENV vars to work alongside example config values Closes #344
This commit is contained in:
Rachel Tublitz
parent
a8ead778b6
commit
bbe744ddba
@ -33,6 +33,7 @@ When submitting a PR:
|
||||
- Ensure your changes do not reduce code coverage of the test suite.
|
||||
- Please do not include merge commits in pull requests; include only commits
|
||||
with the new relevant code.
|
||||
- PR naming conventions - begins with type (fix, feature, doc, chore, etc) and a short description with no period.
|
||||
|
||||
See the main [README.md](/README.md) for information on prerequisites,
|
||||
installing, running and testing.
|
||||
|
||||
2
Makefile
Normal file
2
Makefile
Normal file
@ -0,0 +1,2 @@
|
||||
run-local:
|
||||
RUST_LOG=debug RUST_BACKTRACE=1 cargo run -- --config config/local.toml
|
||||
@ -1,6 +1,11 @@
|
||||
Please remember to consult our [contributing guidelines](https://github.com/mozilla-services/syncstorage-rs/blob/master/CONTRIBUTING.md#sending-pull-requests) before opening your PR.
|
||||
# Description
|
||||
|
||||
- [ ] **Title** begins with _type_ (fix, feature, doc, chore, etc) and a short description with no period
|
||||
- [ ] **Description** outlines the change
|
||||
- [ ] **Test cases** included in the change (if appropriate)
|
||||
- [ ] **Closes** or **Issue** link to associated issue(s)
|
||||
Describe these changes.
|
||||
|
||||
# Testing
|
||||
|
||||
How should reviewers test?
|
||||
|
||||
# Issue(s)
|
||||
|
||||
Closes [link](link).
|
||||
|
||||
63
README.md
63
README.md
@ -5,7 +5,6 @@
|
||||
- [Syncstorage-rs](#syncstorage-rs)
|
||||
- [System Requirements](#system-requirements)
|
||||
- [Local Setup](#local-setup)
|
||||
- [Local DB Setup](#local-db-setup)
|
||||
- [MySQL](#mysql)
|
||||
- [Spanner](#spanner)
|
||||
- [Logging](#logging)
|
||||
@ -25,19 +24,19 @@ Mozilla Sync Storage built with [Rust](https://rust-lang.org).
|
||||
|
||||
## System Requirements
|
||||
|
||||
* [Rust stable](https://rustup.rs)
|
||||
* MySQL 5.7 (or compatible)
|
||||
-* libmysqlclient (`brew install mysql` on macOS, `apt-get install libmysqlclient-dev` on Ubuntu)
|
||||
* [Go](https://golang.org/doc/install)
|
||||
- [Rust stable](https://rustup.rs)
|
||||
- MySQL 5.7 (or compatible)
|
||||
-\* libmysqlclient (`brew install mysql` on macOS, `apt-get install libmysqlclient-dev` on Ubuntu)
|
||||
- [Go](https://golang.org/doc/install)
|
||||
|
||||
Depending on your OS, you may also need to install `libgrpcdev`, and `protobuf-compiler-grpc`.
|
||||
|
||||
## Local Setup
|
||||
|
||||
1. Follow the instructions below to use either MySQL or Spanner. as your DB.
|
||||
1. Follow the instructions below to use either MySQL or Spanner as your DB.
|
||||
2. Now `cp config/local.example.toml config/local.toml`. Open `config/local.toml` and make sure you have the desired settings configured. For a complete list of available configuration options, check out [docs/config.md](docs/config.md).
|
||||
3. `cargo run` - visit `http://localhost:8000/__heartbeat__` to ensure the server is running.
|
||||
|
||||
3. `make run-local` starts the server in debug mode, using your new `local.toml` file for config options. Or, simply `cargo run` with your own config options provided as env vars.
|
||||
4. Visit `http://localhost:8000/__heartbeat__` to make sure the server is running.
|
||||
|
||||
### MySQL
|
||||
|
||||
@ -56,35 +55,38 @@ To setup a fresh MySQL DB and user: (`mysql -u root`):
|
||||
|
||||
### Spanner
|
||||
|
||||
Spanner requires a key in order to access the database. It's important that you know which keys have access to the spanner database. Contact your administrator
|
||||
to find out. One you know the key, log into the [Google Cloud Console Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) page. Be sure to
|
||||
Spanner requires a key in order to access the database. It's important that you know which keys have access to the spanner database. Contact your administrator
|
||||
to find out. One you know the key, log into the [Google Cloud Console Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) page. Be sure to
|
||||
select the correct project.
|
||||
|
||||
* Locate the email identifier of the access key and pick the vertical dot menu at the far right of the row.
|
||||
* Select "*Create Key*" from the pop-up menu.
|
||||
* Select "JSON" from the Dialog Box.
|
||||
- Locate the email identifier of the access key and pick the vertical dot menu at the far right of the row.
|
||||
- Select "_Create Key_" from the pop-up menu.
|
||||
- Select "JSON" from the Dialog Box.
|
||||
|
||||
A proper Key file will be downloaded to your local directory. It's important to safeguard that key file. For this example, we're going to name the file
|
||||
A proper Key file will be downloaded to your local directory. It's important to safeguard that key file. For this example, we're going to name the file
|
||||
`sync-spanner.json` and store it in a subdirectory called `./keys`
|
||||
|
||||
The proper key file is in JSON format. An example file is provided below, with private information replaced by "`...`"
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "service_account",
|
||||
"project_id": "...",
|
||||
"private_key_id": "...",
|
||||
"private_key": "...",
|
||||
"client_email": "...",
|
||||
"client_id": "...",
|
||||
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
|
||||
"token_uri": "https://oauth2.googleapis.com/token",
|
||||
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
|
||||
"client_x509_cert_url": "..."
|
||||
{
|
||||
"type": "service_account",
|
||||
"project_id": "...",
|
||||
"private_key_id": "...",
|
||||
"private_key": "...",
|
||||
"client_email": "...",
|
||||
"client_id": "...",
|
||||
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
|
||||
"token_uri": "https://oauth2.googleapis.com/token",
|
||||
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
|
||||
"client_x509_cert_url": "..."
|
||||
}
|
||||
```
|
||||
|
||||
You can then specify the path to the key file using the environment variable `GOOGLE_APPLICATION_CREDENTIALS` when running the application.
|
||||
|
||||
e.g.
|
||||
|
||||
```bash
|
||||
RUST_LOG=warn GOOGLE_APPLICATION_CREDENTIALS=`pwd`/keys/sync-spanner.json` cargo run -- --config sync.ini
|
||||
```
|
||||
@ -94,7 +96,7 @@ Note, that unlike MySQL, there is no automatic migrations facility. Currently Sp
|
||||
## Logging
|
||||
|
||||
- If you want to connect to the existing [Sentry project](https://sentry.prod.mozaws.net/operations/syncstorage-dev/) for local development, login to Sentry, and go to the page with [api keys](https://sentry.prod.mozaws.net/settings/operations/syncstorage-dev/keys/). Copy the `DSN` value, and `export SENTRY_DSN=DSN_VALUE_GOES_HERE` to the environment when running this project.
|
||||
- Using envlog: set the `RUST_LOG` env var.
|
||||
- Using [env_logger](https://crates.io/crates/env_logger): set the `RUST_LOG` env var.
|
||||
|
||||
## Tests
|
||||
|
||||
@ -109,7 +111,6 @@ RUST_TEST_THREADS=1 && /
|
||||
cargo test
|
||||
```
|
||||
|
||||
|
||||
### End-to-End tests
|
||||
|
||||
Functional tests live in [server-syncstorage](https://github.com/mozilla-services/server-syncstorage/) and can be run against a local server, e.g.:
|
||||
@ -128,7 +129,7 @@ Functional tests live in [server-syncstorage](https://github.com/mozilla-service
|
||||
|
||||
$ ./local/bin/python syncstorage/tests/functional/test_storage.py http://localhost:8000#<SOMESECRET>
|
||||
|
||||
5. Individual tests can be specified via the `SYNC_TEST_PREFIX` env var:
|
||||
5. Individual tests can be specified via the `SYNC_TEST_PREFIX` env var:
|
||||
|
||||
$ SYNC_TEST_PREFIX=test_get_collection \
|
||||
./local/bin/python syncstorage/tests/functional/test_storage.py http://localhost:8000#<SOMESECRET>
|
||||
@ -137,13 +138,11 @@ Functional tests live in [server-syncstorage](https://github.com/mozilla-service
|
||||
|
||||
- `rm Cargo.lock; cargo clean;` - Try this if you're having problems compiling.
|
||||
|
||||
|
||||
## Related Documentation
|
||||
|
||||
* [API docs](https://mozilla-services.readthedocs.io/en/latest/storage/apis-1.5.html)
|
||||
|
||||
* [Code](https://mozilla-services.github.io/syncstorage-rs/syncstorage/)
|
||||
- [API docs](https://mozilla-services.readthedocs.io/en/latest/storage/apis-1.5.html)
|
||||
|
||||
- [Code docs](https://mozilla-services.github.io/syncstorage-rs/syncstorage/)
|
||||
|
||||
[mpl-svg]: https://img.shields.io/badge/License-MPL%202.0-blue.svg
|
||||
[mpl]: https://opensource.org/licenses/MPL-2.0
|
||||
|
||||
@ -1,6 +1,2 @@
|
||||
PORT=8000
|
||||
RUST_BACKTRACE=1
|
||||
RUST_LOG="debug"
|
||||
SENTRY_DSN="see readme for instructions"
|
||||
SYNC_DATABASE_URL="mysql://sample_user:sample_password@localhost/syncstorage_rs"
|
||||
SYNC_MASTER_SECRET="your secret here"
|
||||
database_url = "mysql://sample_user:sample_password@localhost/syncstorage_rs"
|
||||
master_secret = "some_secret_here"
|
||||
Loading…
x
Reference in New Issue
Block a user