“It’s not you – it’s me”
If the instructions in this guide feel a bit much, it’s likely because the Toolkit is still an alpha-version software which assumes a certain technical knowledge. There are technical solutions to simplifying this setup, but these were not prioritised.
Setting up the ledger
The Toolkit requires a working connection with Amazon Web Services, and thus that you have some kind of well-permissioned account or IAM role.
In short, you will need:
- the AWS CLI and an authorised profile in
~/.aws/credentials(see “Installing the AWS CLI v2” - docs.aws.amazon.com) - an existing QLDB ledger, with a blank table in it (see “Creating a QLDB ledger from the AWS Console” - qldbguide.com)
Not required but recommended is an S3 bucket in which to store Toolkit data.
Remember the names of the ledger and of its table. You’ll need them shortly (see “Environment” below).
Environment
After cloning the repository, create an .env file at the root or copy .env.example. The job of this file is to contain variables you really don’t want to share publicly, so keep this out of version control software.
This file must contain:
- AWS access credentials and preferred region
- Details about the ledger and S3 bucket
AWS_ACCESS_KEY_ID="your aws access key"
AWS_SECRET_ACCESS_KEY="your aws secret key"
AWS_REGION="eu-central-1 (or another region)"
BUCKET_NAME="anS3BucketName"
LEDGER_NAME="yourLedgerName"
DOC_TABLE_NAME="yourTableName"
Recommended way of running the Toolkit
The Docker Compose orchestration is composed of several services:
- An Express/TypeScript API
- A plain JS browser extension
- And a frontend
To start the whole app:
$ docker-compose up
Running without Docker
Ensure you’re running node > 10.0 — the recommended version is the LTS, i.e. node v16. If you are using nvm:
$ nvm use --lts
> Now using node v16.13.0
Manually install dependencies for each service:
$ cd ui/ & npm install
$ cd extension/ & npm install
$ npm install
Then use the npm script including all services:
$ npm run all
Storage options
By including a bucket in the .env config, you’re choosing to replicate your archival on S3.
Namely, the Store (src/store/index.ts) will:
- upon receiving an archive request, store the Bundle files both locally and on S3,
- and upon receiving a file request (e.g. the UI fetching thumbnails), serve it from S3.
Is there anybody out there?
API and frontend
The API should be available at http://localhost:3000 — assert this by running:
$ curl http://localhost:3000/list-docs
> [ {...}, {...} ]
The UI should be available at http://localhost:8000 in your web browser of choice. API requests are proxied through the UI. Thus, the following queries are equivalent:
$ curl http://localhost:3000/list-docs // as before
$ curl http://localhost:8000/api/list-docs
Browser extension
The extension should be being bundled on your filesystem. Pop open your browser’s extension runtime by pasting this in the URL bar:
about:debugging#/runtime/this-firefox
Click “Load temporary Add-on…” and navigate to extension/addon to select manifest.json.
The extension should have been loaded in your extension bar, as shown below:
