Installing ABCD

ABCD has two components: the front-end interface that can be used from the command line or as a python module, and the back-end postgresql database.

Installing the database

The backend database can be setup in postgresql by executing the commands contained in the scripts:

sql/01-create.sql
sql/02-views.ql

A docker image that extends the default postgresql image and loads these scripts can be built from source with

docker build . -f Dockerfile.db --tag abcd:db

However automated builds are also provided on dockerhub so this manual build step is not required.

Running the database

To start the database and fork it into the background execute

docker run -d rsecambridge/abcd:db --name abcd_db

which can be stopped again with docker stop abcd_db. As this image extends the default postgresql image, which makes use of docker volumes for data persistance, this can be stopped and started without losing data. To delete the image and the data it is storing, first stop the container, and use docker rm -v abcd_db.

By default this will not expose the service to the outside world - which is a sensible security precaution but can cause trouble trying to connect. To expose the database the -P option to docker can be used to assign a random port number (e.g. 32768) to the database connection. This is then passed to the front-end cli as postgresql://user@host:32768. In the docker image, the database user is 'postgres'.

Installing the frontend

The frontend code a python pacakge (requiring python version 3.6). It can setup directly in the local environment (i.e. installed to a system directory or into a virtual environment):

pip install ~/abcd

if the source has been checked out locally or

pip install git+https://github.com/rse-cambridge/abcd

to install directly from the online version at github. Note that the source code requires python version 3.7.

Alternatively, a docker image is available and can be run directly as

docker run -it --rm abcd:cli

As docker tries to protect containers from each other, some extra options are required to connect the frontend to the backend storage. If the backend is running in a different container on the same host, the containers can be linked:

docker run -it --rm --link abcd_db abcd:cli --db 'postgresql://postgres@abcd_db'

which links to the abcd_db container, and tells the frontend tool where to access it.