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.


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
    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
      esHost: "http://localhost:9200"
    }).then(router => {
      const app = express();
      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
      esHost: "http://localhost:9200"
    }).then(adminApp => {
      const app = express();
        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.


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} />
    • 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
    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