Arranger for Application Developers

Arranger comes in individual pieces that can be flexibly composed together to meet your application’s needs. These include:
Additionally, some packages that are used internally are also published. These include:
  • @arranger/schema: contains the Graphql schema generated and served by @arranger/server.
  • @arranger/mapping-utils: contains utility functions used for computing / interpreting elasticsearch mappings and Arranger metadata about the mappings.
  • @arranger/middleware: responsible for translating SQON and aggregation parameters from the @arranger/server to elasticsearch queries and aggregations.

Server-side

On the server side, @arranger/server and @arranger/admin are the relevant packages.

Some prerequisit:

  • Elasticsearch version 6.6.1 running.
  • Kibana version 6.6.1 (optional)
  • NodeJs version 10

There are multiple ways to get up and running with Arranger on the server-side:

  1. Running a stand-alone all-in-one instance:
  • Using Docker:
    1. The latest arranger server image is available on Dockerhub
    2. Alternatively, you may build an image using the Dockerfile.server file from the Arranger source
  • Running with Node:
    1. Clone the Arranger repo: git clone git@github.com:overture-stack/arranger.git
    2. Navigate to the directory: cd arranger
    3. Install dependencies: npm ci && npm run bootstrap
    4. Navigate to the modules/server directory: cd modules/server
    5. Start the server: npm start

This will start an instance of @arranger/server on port 5050.

By default, this bundle also comes with the admin API from @arranger/admin serverd at /admin/api. From your browser, navigate to http://localhost:5050/admin/graphql to explore this API

Limitation of this approach: the API from @arranger/admin is not meant to be exposed to end-users, hence also not horizontally scalable. For the second a production-ready setup, please use the next option:

  1. Running with custom express apps:
  • Example search app (horizontally scalable):

    import express from 'express';
    import Arranger from '@arranger/server';
    
    const PORT = 9000
    
    Arranger({
      esHost: "http://localhost:9200"
    }).then(router => {
      const app = express();
      app.use(router);
      app.listen(PORT, () => {
        console.log(`⚡️⚡️⚡️ search API listening on port ${PORT} ⚡️⚡️⚡️ `)
      })
    })
    
  • Example admin app (single instance):

    import express from "express";
    import adminGraphql from "@arranger/admin/dist";
    
    const PORT = 8000
    
    adminGraphql({
      esHost: "http://localhost:9200"
    }).then(adminApp => {
      const app = express();
      adminApp.applyMiddleware({
        app,
        path: "/admin"
      });
      app.listen(PORT, () => {
        console.log(`⚡️⚡️⚡️ Admin API listening on port ${PORT} ⚡️⚡️⚡️`)
      })
    })
    

Both applications should be interacting with the same Elasticsearch instance. Since they are two separate applications, they can be scaled separately, with separate authentication and authorization rules.

Browser-side

On the browser side, @arranger/admin-ui and @arranger/components are the relevant packages. Both packages are both written in React, hence we recommend using React for your application for the most seamless integration.

  • @arranger/admin-ui: This package provides the admin interface that is documented in the Arranger for administrator section.

    Integration with your React app:

    1. Install the package: npm i @arranger/admin-ui
    2. Integrate into your app:
    import ArrangerAdmin from '@arranger/admin-ui/dist';
    import { Route, Switch } from 'react-router-dom';
    
    const ArrangerAdminPage = () => (
      <ArrangerAdmin basename="/admin" apiRoot="http://localhost:8000" fetcher={fetch} />
    )
    
    Configurations:
    • basename: tells ArrangerAdmin to treat /admin as the root path for client-side routing.
    • apiRoot: tells ArrangerAdmin to communicate with back-end API hosted at http://localhost:8000
    • fetcher: allows specifying custom data fetcher to use, this is usefull for integrating custom client-side loggins / authorization logics. fetcher must implment the Fetch API.
  • @arranger/components: This package provides UI components that are pre-configured to work with the @arranger/server API. To explore the components this package provide, follow the steps bellow:

    1. Clone the Arranger repo: git clone git@github.com:overture-stack/arranger.git
    2. Navigate to the directory: cd arranger
    3. Install dependencies: npm ci && npm run bootstrap
    4. Navigate to the modules/components directory: cd modules/components
    5. Start the Storybook server: npm run storybook

    A basic repo UI can be found at: arranger/modules/components/stories/Portal.js