AeroGear Sync Server (DEPRECATED)

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

Project moved to apollo-voyager-server repository

Table of Contents

• 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

Architecture

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

Getting Started

1. Install Dependencies

npm install

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

1. Initialize the database.

WARNING: These are destructive actions. they drop and recreate the tables every time.

No sample schema/resolvers

npm run db:init

The Commands below are useful for local development which 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

1. Start the Server

npm run dev

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

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

Postgres

Inspecting

npm run db:shell

Cleanup Postgres

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

Tests

Running Unit Tests

npm run test

Running Integration Tests

Start the database first:

docker-compose -p sync up

In another session, run the tests:

npm run test:integration

Running Individual Tests

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.

Debugging Individual Tests

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

Running all tests with CircleCi CLI

1. Install CircleCi CLI

2. Execute these commands locally:

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

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.

The DevTools window should automatically connect to the debugging session and execution should pause if some breakpoints are set.

Memeolist

What's Memeolist?

Memeolist is an application where the AeroGear community can test AeroGear Mobile Sync Services and SDKs and is based on the dogfood proposal

In memory

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

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

Postgres

To start the application with MemeoList schema and queries with a Postgres source, run the following commands:

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

Authentication and Authorization

By default, the server starts without any authentication and authorization mechanism configured. Please follow the documentation below to see how to enable support for this feature.

Using Keycloak during Local Development

To use Keycloak for authorisation, set the environment variable 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

If you do not have any running keycloak instance, it can be run with docker-compose. Use the separate docker compose file located at the ./keycloak/ folder.

npm run compose:sync:keycloak

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.

Keycloak SSO support

Keycloak integration is supported by providing a location to the 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.

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