niosx/README.md

niosx

Democratising content on the Internet

Archival backend providing core set of APIs and administrative pages.

Installation

Installing niosx is easy! You can clone this project, navigate to /scripts and execute /niosx.sh and follow the instructions on screen. The script uses docker for installation. niosx can be run in different modes depending on the requirements, data load, etc. Please read more about these at scripts/offerings.md.

Running the project locally

Using Docker (recommended for a quick test and/or deployment)

The application needs the JanusGraph backend up and running:

(The docker-compose-test.yaml can be found in /path/to/niosx/conf directory.)

$ docker-compose -f conf/docker-compose-test.yaml up

Tip: Ensure that you set a sufficiently large value for vm.max_map_count in your /etc/sysctl.conf file.

Once the JanusGraph is up and running, pull and run the niosx docker image:

$ docker run --name milli-test -e APPLICATION_SECRET=$APPLICATION_SECRET -p 9000:9000 milliarchives/niosx:1.0-SNAPSHOT

The above command requires you to provide an APPLICATION_SECRET

Using sbt

To run the project locally, you must have sbt installed (version 1.0+). cd into the root of the project and execute sbt run. This would start an sbt shell and run the project on the default port. From here on, you can play with the application using GraphiQL or any other GraphQL compliant application (or by simply using cUrl).

GraphQl API usage

Please explore the graphQl schema for detailed usage. Here are a few sample queries and their responses:

##############
# Example 1. #
##############
mutation {
 addEntity(niosxEntityInput: {
   agencyCode : "Awesome agency!",
   recordId : "http://awesomeness/1",
   unitId : "1",
   title : "Testing entity insert",
   creator : "superglue",
   dateOfCreation : "4-4-2020",
   extent : "4 boxes filled with glue",
   level : "item"
 }){graphId, title, level}
}

###############
# Response 1. #
###############
{
  "data": {
    "addEntity": {
      "graphId": "103e53fc-2fb7-48b0-b5ed-917c5280fba9",
      "agencyCode": "Awesome agency!",
      "title": "Testing entity insert",
      "level": "item",
      "annotations": []
      }
    }
}
##############
# Example 2. #
##############
query {
  findEntity(id : "103e53fc-2fb7-48b0-b5ed-917c5280fba9"){
    graphId, agencyCode, title, level,
    annotations{
      graphId, 
      id,
      body{... on textualBody{value}}
    }
  }
}

###############
# Response 2. #
###############
{
  "data": {
    "findEntity": {
      "graphId": "103e53fc-2fb7-48b0-b5ed-917c5280fba9",
      "agencyCode": "Awesome agency!",
      "title": "Testing entity insert",
      "level": "item",
      "annotations": [
        {
          "graphId": "81be92c1-a370-4ac5-8b72-5a0ba6780efb",
          "id": "https://baseUri/81be92c1-a370-4ac5-8b72-5a0ba6780efb",
          "body": [
            {
              "value": "This is a comment which is just an annotation!"
            }
          ]
        },
        {
          "graphId": "1e71dadb-479c-4aa6-8538-78582c0239b1",
          "id": "https://baseUri/1e71dadb-479c-4aa6-8538-78582c0239b1",
          "body": [
            {
              "value": "Second great comment!"
            }
          ]
        }
      ]
    }
  }
}

The complete schema can be generated by issuing a GET request to the endpoint /graphql-schema.

Contribution | Collaboration

Please reach out to prasoon [at] disroot [dot] org

Caution

This project is under active development and is bound to change rapidly.