Choose your backend

Being open source, you have options: Build on top of a hosted PDA or run your own PDA infrastructure.

This section will help you get going with a PDA and start testing the API in a matter of minutes. There are a few ways to get a running PDA and the approach will depend on your skill level, available time, and actual purpose.

Get a sandbox PDA from Dataswift Developers Portal

The registration process is quick and straightforward. You can read more about how to create an account here. Normally, you should be able to get up and running with a new PDA in a matter of minutes.

Run postman collection

You can find our postman collection here. The collection is able to run using a pre-existing managed PDA (postman.hubat.net). If you choose to use that account, please keep in mind that other developers can see the data in this PDA, DO NOT write any sensitive information on this PDA. If you want to avoid using a PDA with other developers you can use your personal PDA by replacing the following environment variables in postman:

  • hat — your PDA address, eg. myusername.hubofallthings.net

  • username — the first part of the PDA address, eg. postman

  • password — the password of your PDA

The goal of the collection is to showcase basic operations on a PDA. The collection aims to showcase how you can:

  • authenticate with a PDA

  • perform CRUD operations

  • use advanced techniques to bundle data

  • work with data debits

  • upload files

  • fetch and setup existing applications, data plugs and tools

Technology stack

This HAT Microserver implementation is written in Scala (2.12.11) uses the following technology stack:

Running the project - Either via docker-compose (recommended) or building locally

1. Get the Source and the submodules for both of the methods

git clone https://github.com/Hub-of-all-Things/HAT2.0.git cd HAT2.0 git submodule init git submodule update

2. Configure your /etc/hosts

127.0.0.1 bobtheplumber.example.com

3a. Using docker-compose

cd /deployment/docker docker-compose up

When the build finishes, open https://bobtheplumber.example.com:9001 in a browser. Standard account login password is testing.

3b. Building locally

HAT Setup

HAT runs as a combination of a backing PostgreSQL database (with a public schema for flattened data storage) and a software stack that provides logic to work with the schema using HTTP APIs.

To run it from source in a development environment two sets of tools are required:

To launch the HAT, follow these steps:

  1. Create the database, which we assume is available as localhost:

    > createdb testhatdb1
    > createuser testhatdb1
    > psql postgres -c "GRANT CREATE ON DATABASE testhatdb1 TO testhatdb1"
  2. Compile the project:

    > sbt compile
  3. Add custom local domain mapping to your /etc/hosts file. This will make sure when you go to the defined address from your machine you will be pointed back to your own machine. E.g.:

    127.0.0.1 bobtheplumber.example.com
  4. Run the project:

    > sbt "project hat" "run -Dconfig.resource=dev.conf"

You're all set!

Customising your development environment

Your best source of information on how the development environment could be customised is the hat/conf/dev.conf configuration file. Make sure you run the project locally with the configuration enabled (using the steps above) or it will just show you the message that the HAT could not be found.

Among other things, the configuration includes:

  • host names alongside port numbers of the test HATs (http://bobtheplumber.example.com:9000)

  • access credentials used to log in as the owner or restricted platform user into the HAT (the default password is a very unsafe testing)

  • database connection details (important if you want to change your database setup above)

  • private and public keys used for token signing and verification

Specifically, it has 4 major sections:

  • Enables the development environment self-initialisation module:

    play.modules {
    enabled += "org.hatdex.hat.modules.DevHatInitializationModule"
    }
  • Sets the list of database evolutions to be executed on initialisation:

    devhatMigrations = [
    "evolutions/hat-database-schema/11_hat.sql",
    "evolutions/hat-database-schema/12_hatEvolutions.sql",
    "evolutions/hat-database-schema/13_liveEvolutions.sql",
    "evolutions/hat-database-schema/14_newHat.sql"]
  • devhats list sets out the list of HATs that are served by the current server, for

    each including owner details to be initialised with and database access

    credentials. Each specified database must exist before launching the server

    but are initialised with the right schema at start time

  • hat section lists all corresponding HAT configurations to serve, here

    you could change the HAT domain name, owner's email address or public/private

    keypair used by the HAT for its token operations

Additional information