QLDB Bicycle Licence

The QLDB Bicycle Licence application is a sample application to demonstrate some of the capabilities of Amazon QLDB and how it can be used to build out a serverless event-driven application.

The basic architecture overview of the application is shown below:

Each seperate deployment is setup in a different folder in this repository. This allows the application to be deployed one component at a time.

Deployments

Once the repository is cloned, it is important to deploy components in a specific order. By default, all deployments will use a stage name of dev, but this can be overridden using the --stage attribute.

API Gateway

The first component to be deployed is the centralised API Gateway. This is used to provide a single endpoint

cd apigateway
npm ci
npm run sls -- deploy --stage {stage-name}

For more information about the API Gateway setup, see the individual readme file.

Backend

Next to be deployed are the backend components, consisting of AWS Lambda functions and Amazon QLDB

cd backend
npm ci
sls deploy [--stage {stage-name}]

The API endpoints will be output when the components are deployed. You will need to make a note of the base URL endpoint for the next section.

endpoints:
  POST - https://{example}.execute-api.eu-west-1.amazonaws.com/dev/licences
  PUT - https://{example}.execute-api.eu-west-1.amazonaws.com/dev/licences
  PUT - https://{example}.execute-api.eu-west-1.amazonaws.com/dev/licences/contact
  GET - https://{example}.execute-api.eu-west-1.amazonaws.com/dev/licences/{licenceid}
  GET - https://{example}.execute-api.eu-west-1.amazonaws.com/dev/licences/history/{licenceid}
  DELETE - https://{example}.execute-api.eu-west-1.amazonaws.com/dev/licences

For more information about the backend setup, see the individual readme file.

Frontend

At this point, the UI can be deployed and configured. The first step is to update the frontend Amplify configuration in ./frontend/src/index.js with the base URL endpoint.

Amplify.configure({
  API: {
    endpoints: [
      {
        endpoint:
          "https://{example}.execute-api.eu-west-1.amazonaws.com/dev",
        name: "ApiGatewayRestApi",
        region: "eu-west-1",
      },
    ],
  },
});

The frontend can then be run locally using the following commands:

cd frontend
npm ci
npm run start

Setting up QLDB Streams

QLDB has the functionality available to stream out all revisions that have been made to a journal since it was first created using QLDB Streams. There are two examples available to deploy - one which uses DynamoDB and one which uses Elasticsearch. They are setup in different folders to allow them to be managed individually. Please note that some of these services, especially Elasticsearch, will incur charges on your AWS account.

Streams DynamoDB

The Streams DynamoDB component, consists of a QLDB Stream that publishes records to a Kinesis Data Stream, and a Lambda function that consumes messages from this stream and populates a table in DynamoDB. There is also an enquiry exposed against DynamoDB. This can be deployed as follows:

cd streams-dynamodb
npm ci
npm run sls -- deploy [--stage {stage-name}]

Streams Elasticsearch

The Streams Elasticsearch component, consists of a QLDB Stream that publishes records to a Kinesis Data Stream, and a Lambda function that consumes messages from this stream and populates an index in Amazon Elasticsearch. There is also an enquiry exposed against Elasticsearch. This can be deployed as follows:

cd streams-es
npm ci
npm run sls -- deploy [--stage {stage-name}]

In some cases, the initial deployment may fail with the following error message:

'ValidationException: Before you can proceed, you must enable a service-linked role to give Amazon ES permissions to access your VPC'

In this case, create a service-linked role first using the AWS CLI with the following command:

aws iam create-service-linked-role --aws-service-name es.amazonaws.com