This repository has been archived by the owner on May 31, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 16
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #52 from danielpassos/README
Improve README
- Loading branch information
Showing
1 changed file
with
152 additions
and
130 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,216 +1,238 @@ | ||
| # aerogear-data-sync-server | ||
| # AeroGear Sync Server | ||
|
|
||
| GraphQL based data sync server for mobile, with backend integration capabilities | ||
|
|
||
| [](https://circleci.com/gh/aerogear/data-sync-server) | ||
| [](https://circleci.com/gh/aerogear/data-sync-server) | ||
| [](https://coveralls.io/github/aerogear/data-sync-server) | ||
| [](http://www.apache.org/licenses/LICENSE-2.0) | ||
| [](https://standardjs.com) | ||
|
|
||
| ## Getting Started | ||
| GraphQL based data sync server for mobile, with backend integration capabilities | ||
|
|
||
| ### Install Dependencies | ||
| ## Table of content | ||
|
|
||
| * [Architecture](#architecture) | ||
| * [Configuration](#configuration) | ||
| * [Getting Started](#getting-started) | ||
| * [Postgres](#postgres) | ||
| + [Inspecting](#inspecting) | ||
| + [Cleanup Postgres](#cleanup-postgres) | ||
| * [Tests](#tests) | ||
| + [Running Unit Tests](#running-unit-tests) | ||
| + [Running Integration tests:](#running-integration-tests-) | ||
| + [Running all tests with CircleCi CLI](#running-all-tests-with-circleci-cli) | ||
| + [Running Individual Tests](#running-individual-tests) | ||
| + [Debugging Individual Tests](#debugging-individual-tests) | ||
| * [Memeolist](#memeolist) | ||
| + [What's Memeolist?](#what-s-memeolist-) | ||
| + [In memory](#in-memory) | ||
| + [Postgres](#postgres-1) | ||
|
|
||
| ``` | ||
| npm install | ||
| ``` | ||
| ## Architecture | ||
|
|
||
| ### Start and Initialize the Database | ||
| The baseline architecture is shown below: | ||
|
|
||
| Use docker compose to start the database(s). | ||
|  | ||
|
|
||
| ``` | ||
| docker-compose -p aerogeardatasyncserver up | ||
| ``` | ||
| 1. The [GraphQL](http://graphql.github.io/) Data Schema, Resolvers etc.. are defined in the [Data Sync UI](https://github.com/aerogear/data-sync-ui) | ||
| 1. All this config is deployed to the Data Sync GraphQL Server | ||
| 1. The developer generates typed Models for use in their App based on the schema defined | ||
| 1. The developer executes queries, mutations & subsdcriptions in their App, which uses the [Apollo GraphQL client](https://www.apollographql.com/client/) to talk to the server. [The Apollo GraphQL Client](https://www.apollographql.com/client/) is auto configured by the AeroGear SDK e.g. it knows what the Data Sync GraphQL Server url is. | ||
| 1. The Data Sync GraphQL Server executes the corresponding resolvers for queries, mutations & subscriptions. | ||
| 1. Configured Authentication & Autohorizatin checks are applied | ||
| 1. Logging & Metrics data is gathered from the Server & connected Clients | ||
|
|
||
| There are 2 Postgres instances defined in docker-compose configuration: | ||
| 1. For storing the configuration of the sync server itself | ||
| 2. For storing the [Memeolist](#whats-memeolist) data. | ||
| ## Configuration | ||
|
|
||
| Since docker-compose is only used with development, starting up the Postgres instance for [Memeolist](#whats-memeolist) | ||
| will not cause any harm. | ||
| This server requires a bunch of environment variables to be set. If they're not set, defaults for development will be used. | ||
|
|
||
| Initialize the database in another terminal. | ||
| * `AUDIT_LOGGING`: : If true, audit logs of resolver operations will be logged to stdout. Defaults to true. | ||
| * `POSTGRES_DATABASE`: Name of the Postgres database. Defaults to `aerogear_data_sync_db` | ||
| * `POSTGRES_USERNAME`: Username to use when connecting Postgres. Defaults to `postgresql` | ||
| * `POSTGRES_PASSWORD`: Password to use when connecting Postgres. Defaults to `postgres` | ||
| * `POSTGRES_HOST`: Postgres host name. Defaults to `127.0.0.1` | ||
| * `POSTGRES_PORT`: Postgres port. Defaults to `5432` | ||
| * `SCHEMA_LISTENER_CONFIG`: Configuration of the config listening mechanism. Defaults to listening to a Postgres channel. | ||
| Value of this environment variable must be a base64 encoded JSON. See below for an example. | ||
|
|
||
| ```shell | ||
| $ echo ' | ||
| { | ||
| "type": "postgres", | ||
| "config": { | ||
| "channel": "aerogear-data-sync-config", | ||
| "database": "aerogear_data_sync_db", | ||
| "user": "postgresql", | ||
| "password": "postgres", | ||
| "host": "127.0.0.1", | ||
| "port": "5432" | ||
| } | ||
| } | ||
| ' | base64 --wrap=0 | ||
|
|
||
| > CnsKICAidHlwZSI6ICJwb3N0Z3JlcyIsCiAgImNvbmZpZyI6IHsKICAgICJjaGFubmVsIjogImFlcm9nZWFyLWRhdGEtc3luYy1jb25maWciLAogICAgImRhdGFiYXNlIjogImFlcm9nZWFyX2RhdGFfc3luY19kYiIsCiAgICAidXNlcm5hbWUiOiAicG9zdGdyZXNxbCIsCiAgICAicGFzc3dvcmQiOiAicG9zdGdyZXMiLAogICAgImhvc3QiOiAiMTI3LjAuMC4xIiwKICAgICJwb3J0IjogIjU0MzIiIAogIH0gCn0KCg== | ||
| ``` | ||
| # no sample schema/resolvers | ||
| npm run db:init | ||
| Currently only Postgres channel listening is supported. | ||
|
|
||
| # sample schema/resolvers for memeolist - in-memory data source | ||
| npm run db:init:memeo:inmem | ||
| ## Getting Started | ||
|
|
||
| # sample schema/resolvers for memeolist - Postgres data source | ||
| npm run db:init:memeo:postgres | ||
| ``` | ||
| 1. Install Dependencies | ||
|
|
||
| ```shell | ||
| npm install | ||
| ``` | ||
|
|
||
| 1. Start and initialize the database | ||
|
|
||
| Use docker compose to start the database(s). | ||
|
|
||
| ```shell | ||
| docker-compose -p aerogeardatasyncserver up | ||
| ``` | ||
|
|
||
| There are 2 Postgres instances defined in docker-compose configuration: | ||
|
|
||
| `npm run db:init*` commands set up the necessary tables. **Those are destructive actions.** | ||
| They drop and recreate the tables every time. | ||
| 1. For storing the configuration of the sync server itself | ||
| 1. For storing the [Memeolist](#whats-memeolist) data. | ||
|
|
||
| `npm run db:init:memeo:*` commands are useful for local development which and seed the database with config and tables | ||
| Since docker-compose is only used with development, starting up the Postgres instance for [Memeolist](#whats-memeolist) will not cause any harm. | ||
|
|
||
| 1. Initialize the database. | ||
|
|
||
| **Those are destructive actions.** They drop and recreate the tables every time. | ||
|
|
||
| No sample schema/resolvers | ||
|
|
||
| ```shell | ||
| npm run db:init | ||
| ``` | ||
|
|
||
| Commands below are useful for **local development** which and seed the database with config and tables | ||
| for [Memeolist](#whats-memeolist) sample application. | ||
|
|
||
| ### Start the Server | ||
| Sample schema/resolvers for memeolist - in-memory data source | ||
| ```shell | ||
| npm run db:init:memeo:inmem | ||
| ``` | ||
|
|
||
| ``` | ||
| npm run dev | ||
| ``` | ||
| Sample schema/resolvers for memeolist - Postgres data source | ||
| ```shell | ||
| npm run db:init:memeo:postgres | ||
| ``` | ||
|
|
||
| Go to http://localhost:8000/graphiql for an interactive query brower. | ||
| The graphql endpoint is at `/graphql`. | ||
| The subscriptions websocket is at `/subscriptions`. | ||
| 1. Start the Server | ||
|
|
||
| ### Inspecting Postgres | ||
| ```shell | ||
| npm run dev | ||
| ``` | ||
|
|
||
| ``` | ||
| 1. Go to http://localhost:8000/graphiql for an interactive query brower. | ||
|
|
||
| The **graphql endpoint** is at `/graphql`. | ||
| The **subscriptions websocket** is at `/subscriptions`. | ||
|
|
||
| ## Postgres | ||
|
|
||
| ### Inspecting | ||
|
|
||
| ```shell | ||
| npm run db:shell | ||
| ``` | ||
|
|
||
| ### Cleanup Postgres | ||
|
|
||
| The Postgres container started by `docker-compose` can be stopped with `Ctrl + C`. To remove it fully: | ||
|
|
||
| ``` | ||
| ```shell | ||
| docker-compose -p aerogeardatasyncserver rm | ||
|
|
||
| Going to remove aerogeardatasyncserver_postgres_1 | ||
| Are you sure? [yN] y | ||
| ``` | ||
|
|
||
| ## Tests | ||
|
|
||
| ### Running Unit Tests | ||
|
|
||
| ``` | ||
| ```shell | ||
| npm run test:unit | ||
| ``` | ||
|
|
||
| ### Running Integration tests: | ||
|
|
||
| Start the database first: | ||
| ``` | ||
| docker-compose -p aerogeardatasyncserver up | ||
| ``` | ||
| Start the database first: | ||
|
|
||
| In another session, run the tests: | ||
| ``` | ||
| npm run test:integration | ||
| ``` | ||
| ```shell | ||
| docker-compose -p aerogeardatasyncserver up | ||
| ``` | ||
|
|
||
| ### Running all tests with CircleCi CLI | ||
| In another session, run the tests: | ||
|
|
||
| ```shell | ||
| npm run test:integration | ||
| ``` | ||
|
|
||
| Install CircleCi CLI using this link: https://circleci.com/docs/2.0/local-cli/ | ||
| ### Running all tests with CircleCi CLI | ||
|
|
||
| Then execute these command locally: | ||
| 1. Install [CircleCi CLI](https://circleci.com/docs/2.0/local-cli/) | ||
| 1. Execute these command locally: | ||
|
|
||
| ``` | ||
| # CircleCi CLI doesn't support workflows yet | ||
| circleci build --job unit_test | ||
| circleci build --job integration_test | ||
| ``` | ||
| ```shell | ||
| # CircleCi CLI doesn't support workflows yet | ||
| circleci build --job unit_test | ||
| circleci build --job integration_test | ||
| ``` | ||
|
|
||
| ### Running Individual Tests | ||
|
|
||
| Assuming you have `npm@5.2.0` or greater you can do the following: | ||
|
|
||
| ``` | ||
| ```shell | ||
| npx ava /path/to/test.js | ||
| ``` | ||
|
|
||
| `npx` will ensure the correct version of ava (specified in package.json) is used. | ||
|
|
||
| ### Debugging Individual Tests | ||
|
|
||
| The easiest way to debug tests is using Chrome DevTools. Use [inspect-process](https://npm.im/inspect-process) to easily launch a debugging session with Chrome DevTools. | ||
| The easiest way to debug tests is using [Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools/). Use [inspect-process](https://npm.im/inspect-process) to easily launch a debugging session with Chrome DevTools. | ||
|
|
||
| ``` | ||
| ```shell | ||
| npm install -g inspect-process | ||
| ``` | ||
|
|
||
| * In chrome go to [`chrome://inspect`](chrome://inspect/) | ||
| * Click on 'Open dedicated DevTools for Node.' This will open a new DevTools window. | ||
| * Click on 'add folder to workspace' and use the wizard to open this project. | ||
| * Go to the appropriate test file (or code that's being tested) and set a breakpoint | ||
| * Now run the individual test as follows: | ||
| 1. In chrome go to [`chrome://inspect`](chrome://inspect/) | ||
| 1. Click on 'Open dedicated DevTools for Node.' This will open a new DevTools window. | ||
| 1. Click on 'add folder to workspace' and use the wizard to open this project. | ||
| 1. Go to the appropriate test file (or code that's being tested) and set a breakpoint | ||
| 1. Now run the individual test as follows: | ||
|
|
||
| ``` | ||
| ```shell | ||
| inspect node_modules/ava/profile.js some/test/file.js | ||
| ``` | ||
|
|
||
| The DevTools window should automatically connect to the debugging session and execution should pause if some breakpoints are set. | ||
|
|
||
| # Configuration | ||
|
|
||
| This server requires a bunch of environment variables to be set. If they're not set, defaults for development will be used. | ||
|
|
||
| * `AUDIT_LOGGING`: : If true, audit logs of resolver operations will be logged to stdout. Defaults to true. | ||
| * `POSTGRES_DATABASE`: Name of the Postgres database. Defaults to `aerogear_data_sync_db` | ||
| * `POSTGRES_USERNAME`: Username to use when connecting Postgres. Defaults to `postgresql` | ||
| * `POSTGRES_PASSWORD`: Password to use when connecting Postgres. Defaults to `postgres` | ||
| * `POSTGRES_HOST`: Postgres host name. Defaults to `127.0.0.1` | ||
| * `POSTGRES_PORT`: Postgres port. Defaults to `5432` | ||
| * `SCHEMA_LISTENER_CONFIG`: Configuration of the config listening mechanism. Defaults to listening to a Postgres channel. | ||
| Value of this environment variable must be a base64 encoded JSON. See below for an example. | ||
|
|
||
| ``` | ||
| $ echo ' | ||
| { | ||
| "type": "postgres", | ||
| "config": { | ||
| "channel": "aerogear-data-sync-config", | ||
| "database": "aerogear_data_sync_db", | ||
| "user": "postgresql", | ||
| "password": "postgres", | ||
| "host": "127.0.0.1", | ||
| "port": "5432" | ||
| } | ||
| } | ||
| ' | base64 --wrap=0 | ||
| > CnsKICAidHlwZSI6ICJwb3N0Z3JlcyIsCiAgImNvbmZpZyI6IHsKICAgICJjaGFubmVsIjogImFlcm9nZWFyLWRhdGEtc3luYy1jb25maWciLAogICAgImRhdGFiYXNlIjogImFlcm9nZWFyX2RhdGFfc3luY19kYiIsCiAgICAidXNlcm5hbWUiOiAicG9zdGdyZXNxbCIsCiAgICAicGFzc3dvcmQiOiAicG9zdGdyZXMiLAogICAgImhvc3QiOiAiMTI3LjAuMC4xIiwKICAgICJwb3J0IjogIjU0MzIiIAogIH0gCn0KCg== | ||
| ``` | ||
| Currently only Postgres channel listening is supported. | ||
|
|
||
|
|
||
| ## Running on Kubernetes | ||
|
|
||
| TODO | ||
|
|
||
| ## Architecture | ||
|
|
||
| The baseline architecture is shown below: | ||
|
|
||
|  | ||
|
|
||
| 1. The GraphQL Data Schema, Resolvers etc.. are defined in the Data Sync Admin UI | ||
| 2. All this config is deployed to the Data Sync GraphQL Server | ||
| 3. The developer generates typed Models for use in their App based on the schema defined | ||
| 4. The developer executes queries, mutations & subsdcriptions in their App, which uses the Apollo GraphQL client to talk to the server. The Apollo GraphQL Client is auto configured by the AeroGear SDK e.g. it knows what the Data Sync GraphQL Server url is. | ||
| 5. The Data Sync GraphQL Server executes the corresponding resolvers for queries, mutations & subscriptions. | ||
| 6. Configured Authentication & Autohorizatin checks are applied | ||
| 7. Logging & Metrics data is gathered from the Server & connected Clients | ||
|
|
||
|
|
||
| ## Memeolist | ||
|
|
||
| ### What's Memeolist? | ||
|
|
||
| Memeolist is an application where AeroGear team targets testing AeroGear mobile services and SDKs on it. | ||
|
|
||
| You can see the specification for it here: https://github.com/aerogear/proposals/blob/master/dogfood.md | ||
| Memeolist is an application where AeroGear team targets testing AeroGear mobile Sync services and SDKs on it [based on the dogfood proposal](https://github.com/aerogear/proposals/blob/master/dogfood.md) | ||
|
|
||
| There is some tooling adjusted to create Memeolist app's backend within the project. | ||
|
|
||
| ### Memeolist - In memory | ||
| ### In memory | ||
|
|
||
| To start the application with MemeoList schema and queries with an in-memory data source, run these commands: | ||
| ``` | ||
| docker-compose -p aerogeardatasyncserver up | ||
|
|
||
| ```shell | ||
| docker-compose -p aerogeardatasyncserver up -d | ||
| npm run db:init:memeo:inmem | ||
| npm run dev:memeo | ||
| ``` | ||
|
|
||
| ### Memeolist - Postgres | ||
| ### Postgres | ||
|
|
||
| To start the application with MemeoList schema and queries with an Postgres source, run these commands: | ||
| ``` | ||
| docker-compose -p aerogeardatasyncserver up | ||
|
|
||
| ```shell | ||
| docker-compose -p aerogeardatasyncserver up -d | ||
| npm run db:init:memeo:postgres | ||
| npm run dev:memeo | ||
| ``` | ||
| ``` |