Deployment

Deploying the Dashboard

Indexing Social Media Posts

Before you can deploy the dashboard you will need to produce an Elasticsearch index containing the social media posts you wish to analyse. Whilst the data obtainable from most platforms comes as JSON, which could be indexed as-is by Elasticsearch, in most cases the files will need to be modified so that they follow the specific structure assumed by the dashboard. As the dashboard was originally developed to analyse X/Twitter data which had been proicessed by the GATE Hate application, the expected format is GATE JSON.

GATE JSON stores the text of a post in the top level text field while almost everything else is then treated as an annotation (i.e. information associated with a text span). For example...

{
    "text": "This is the text of the post",
    "entities": {
        "Tweet": {
            // metadata from the original post
        },
        "Abuse": {
            // information relating to abuse
        }
    },
    "tweet_kind": "original",
    "platform": "Twitter"
}

Note that regardless of the platform the post is from the annotation listed in the entities section is Tweet and it's content must conform to the v1.1 X/Twitter JSON -- a sample JSON file is available if the X/Twitter documentation for this format disappears. Note that not all fields are necessary, but the fields related to user information, post IDs, and who is being replied to must be present. If you have data from another platform it will need to be converted into this format prior to indexing.

Configuration Files

Once you have an Elasticsearch index ready to use, you then need to configure the dashboard so that it knows where the index is and what accounts you are monitoring. This is done via a YAML file.

dashboards:
  example: // this key forms pat of the URL for the dashboard
    title: A brief title for the dashboard
    description: A slightly longer description of the dashboard
    image: <URL to an small image to use as an icon>
    from: <date in YYYY-MM-DD format>
    to: <date as above or live>
    index: <an Elasticsearch index pattern>
    elastic:
      host: <URL to the Elasticseach instance>
      pathPrefix: <optional path prefix>
      username: <required if auth is enabled on the instance>
      password: <required if auth is enabled on the instance>
    abuseHierarchy: // the map here matches the GATE Hate hierarchy
      reputation:
        - gendered reputation
      personal:
        - sexist
        - homophobic
        - racist
        - general
      belief:
        - religious
        - political
    users: // you can specify multiple users
      -
        name: John Smith // can be a list
        handle: johnsmith
        platform: Twitter 

Note that multiple dashboards can be defined under the top level dashboards element allowing one deployment to support multiple dashboards each of which could be monitoring multiple accounts.

The application.yml file shoud be placed in the root of the repository next to the docker-compose.yml file.

Building and Running the Docker Container

The dashboard has been designed to be deployed as a Docker container. We do not currently publish images but assuming you have Docker installed then you can easily build an image using the correct tags etc. via Docker Compose with the command:

docker compose build

Once the image has been built then the dashboard can be brought up using the standard compose command

docker compose up -d