GraphQL based data sync server for mobile, with backend integration capabilities

• Architecture
• Configuration
• Getting Started
• Postgres
  • Inspecting
  • Cleanup Postgres
• Tests
  • Running Unit Tests
  • Running Integration tests:
  • Running all tests with CircleCi CLI
  • Running Individual Tests
  • Debugging Individual Tests
• Memeolist
  • What's Memeolist?
  • In memory
  • Postgres

The baseline architecture is shown below:

1. The GraphQL Data Schema, Resolvers etc.. are defined in the Data Sync 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

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.

1. Install Dependencies

   npm install

2. Start and initialize the database

   Use docker compose to start the database(s).

   docker-compose -p sync up

   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 data.

   Since docker-compose is only used with development, starting up the Postgres instance for Memeolist will not cause any harm.

3. Initialize the database.

   Those are destructive actions. They drop and recreate the tables every time.

   No sample schema/resolvers

   npm run db:init

   Commands below are useful for local development which and seed the database with config and tables for Memeolist sample application.

   Sample schema/resolvers for memeolist - in-memory data source

   npm run db:init:memeo:inmem

   Sample schema/resolvers for memeolist - Postgres data source

   npm run db:init:memeo:postgres

4. Start the Server

   npm run dev

5. Go to http://localhost:8000/graphql for an interactive query browser.

   The graphql endpoint is at /graphql.
   The subscriptions websocket is at /subscriptions.

To use Keycloak for authorisation, set the env var

KEYCLOAK_CONFIG_FILE

to point to a config file. An example can be seen at ./keycloak/keycloak.json.

To use Keycloak with Sync complete the steps above in the Getting Started section to create and initialise the database, then start the application by running:

npm run dev

Once the application is started, visit http://localhost:8000/graphql. You should be redirected to the login for your realm. You can log in here with the example credentials:

Once logged in and you are redirected to the Graphql playground you will need to (for the time being) manually attach the Bearer token used by Keycloak to each request. To get this token, visit http://localhost:8000/token and put this whole string in the HTTP HEADERS section of Graphql Playground.

Each request should now be autorised via Keycloak. To logout visit http://localhost:8000/logout.

npm run db:shell

The Postgres container started by docker-compose can be stopped with Ctrl + C. To remove it fully:

docker-compose -p sync rm

Going to remove ...
Are you sure? [yN] y

npm run test:unit

Start the database first:

docker-compose -p sync up

In another session, run the tests:

npm run test:integration

1. Install CircleCi CLI

2. Execute these command locally:

   # CircleCi CLI doesn't support workflows yet
   circleci build --job unit_test
   circleci build --job integration_test

Assuming you have [email protected] or greater you can do the following:

npx ava /path/to/test.js

npx will ensure the correct version of ava (specified in package.json) is used.

The easiest way to debug tests is using Chrome DevTools. Use inspect-process to easily launch a debugging session with Chrome DevTools.

npm install -g inspect-process

1. In chrome go to chrome://inspect
2. Click on 'Open dedicated DevTools for Node.' This will open a new DevTools window.
3. Click on 'add folder to workspace' and use the wizard to open this project.
4. Go to the appropriate test file (or code that's being tested) and set a breakpoint
5. Now run the individual test as follows:

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.

Memeolist is an application where AeroGear team targets testing AeroGear mobile Sync services and SDKs on it based on the dogfood proposal

To start the application with MemeoList schema and queries with an in-memory data source, run these commands:

docker-compose -p sync up
npm run db:init:memeo:inmem
npm run dev:memeo

To start the application with MemeoList schema and queries with an Postgres source, run these commands:

docker-compose -p sync up
npm run db:init:memeo:postgres
npm run dev:memeo

By default server starts without any authentication and authorization mechanism. Please follow documentation bellow to see how

Keycloak integration is supported by providing location to keycloak configuration file

KEYCLOAK_CONFIG_FILE=keycloak/keycloak.json

You can also execute npm run dev:keymemeo to run the server preconfigured with an example keycloak server.

Memeolist example application requires a keycloak realm to be configured. See Keycloak realm configuration for more details.

Currently this file points to a demo Keycloak instance hosted at https://keycloak.security.feedhenry.org. If you wish, you can also use the realm-export file mentioned above to create a realm on your own Keycloak instance.

The credentials currently available for use on this realm are:

u: admin/voter
p: 123

Currently, the roles available in the demo instance for use are 'admin' and 'voter'.

See the "Using Keycloak for local development" above for details about how to use authorisation once it is configured.