Recently we’ve begun the move to running the Keep API using Docker. There are numerous benefits that are realized by this move, but rather than enumerate them here, let’s just get an fully functioning Keep installation up and running in this Step by Step tutorial and let you judge for yourself.

Prerequisites

You’ll need Docker running on the host machine. This could be a Linux, Mac, or Windows computer, and there are enough variations that I’ll leave this as an exercise for the reader. In this example we’ll be working with Docker running on my iMac.

You will also need the AWS CLI for your host operating system. The AWS CLI toolset is installed automatically on AWS Images, but for your workstation, you’ll need to download and install a copy.

On MacOS use brew

brew install awscli

On Windows use the Amazon .MSI installer for windows available at https://docs.aws.amazon.com/cli/latest/userguide/install-windows.html

Installation

We’ve published a handy script for downloading the necessary images (Keep API, SEQ, MongoDB) and running them, which you can download from the dev api service: https://dev-api.feenicsdev.com/install-keep

Let’s take a closer look at the install-keep bash script

aws configure set aws_access_key_id AKIARX6BLTCOZB5RAU52 --profile ecrread
aws configure set aws_secret_access_key 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 --profile ecrread
aws configure set default.region us-east-1 --profile ecrread
$(aws ecr get-login --no-include-email --region us-east-1 --profile ecrread)
curl -s https://dev-api.feenicsdev.com/docker-compose.yml -o docker-compose.yml
docker-compose pull
docker-compose up -d

The first three lines of the script configure a new AWSCLI profile called ecrread with access_key and secret that allows the holder of these keys readonly access to our Docker repository in AWS.

The forth line downloads a command from AWS and runs it. This command configures the docker daemon with temporary login credentials based on the access keys in the ecrread profile.

With the docker daemon able to login to the Feenics Docker Repository the next step is to download a copy of the docker-compose.yaml and pull the images named in the package, and run the packages as a background service, which is the last 3 lines of the script file.

You’re encouraged to read through the docker-compose file at your leasure. There are just a few key points to highlight.

• There are four services that are defined in this composition.
  • the SEQ service, is a common service used for diagnostics
  • the MongoDB service
  • the setup service, that verifies the schema of the database is current
  • the api service
• There are two network ports that are mapped to the outside world.
  • Port 5000 is mapped to port 80 for the API service
  • Port 8080 is mapped to port 80 for the SEQ service
  • the mongo service does not have an external mapping. The only access to the mongo service is on the internal docker network (or by docker exec to the container)
• The compose file identifies the name of the database, the name of the root instance, administrator username and password to be configured by the setup service, and then to be used by the running web service. These values can be edited
• The compose file maps internal volumes to an external folder called /dockerdata this name and location can be changed. (see Docker Docs for issues with mapping volumes on MacOS)

Confirm the operation

We can configure a keepcli profile to connect to the locally running keep setup and verify that all is running as expected.

keepcli configure -@local -a http://localhost:5000 -i Root -u Administrator -p Password -e ws://localhost:5001

If the configuration is sucessful then we can test both the API service and the EventPublisher service by opening two seperate windows, one to subscribe to events:

keepcli subscribe -@local | jq '{d:.PublishedOn."$date"| (. / 1000 | todate),m:.MessageLong, et:.ObjectLinks[] | select(.Relation=="PublishingEventType") | .CommonName}'

The second window runs the test

keepcli test -@local

Observe the sucessful login event in the event subscriber window and the confirmation of a sucessful login in the keepcli test window.