diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 55824753..26284347 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..5b0d6fac --- /dev/null +++ b/Makefile @@ -0,0 +1,2 @@ +run-local: + RUST_LOG=debug RUST_BACKTRACE=1 cargo run -- --config config/local.toml \ No newline at end of file diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md index e3ad1743..e5d0a4fe 100644 --- a/PULL_REQUEST_TEMPLATE.md +++ b/PULL_REQUEST_TEMPLATE.md @@ -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) \ No newline at end of file +Describe these changes. + +# Testing + +How should reviewers test? + +# Issue(s) + +Closes [link](link). diff --git a/README.md b/README.md index 9ebd55c0..f98ee191 100644 --- a/README.md +++ b/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# -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# @@ -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 diff --git a/config/local.example.toml b/config/local.example.toml index 40449f87..60c43344 100644 --- a/config/local.example.toml +++ b/config/local.example.toml @@ -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" \ No newline at end of file +database_url = "mysql://sample_user:sample_password@localhost/syncstorage_rs" +master_secret = "some_secret_here" \ No newline at end of file