Page History

A guide to deploying SimplyE using Docker containers.

 Contents:

...

1. Install Docker. Docker has step-by-step instructions to grab its most up-to-date version. Depending on your package manager, you could also install a slightly older version with: sudo apt-get install docker-ce or sudo yum install docker-ce.
2. Create any dependent, temporary containers (optional) for integrations like Elasticsearch and Postgres. We don't recommend using containers in the long-term for holding or maintaining data. However, if you just want to get a sense of how your Circulation Manager will work, containers are a quick option. Instructions for integrating Elasticsearch and Postgres via Docker can be found below.
3. Get the Docker images for the Library Simplified Circulation Manager. Run:

   $ sudo docker pull nypl/circ-

...

webapp && sudo docker pull nypl/circ-scripts

Running Circulation Manager containers

...

Anchor
_55slrod1jusc _55slrod1jusc

Example docker run script

$    $ sudo docker run -d --name circ-scripts \ -e TZ="US/Central" \ -e SIMPLIFIED_DB_TASK='init' \ -e SIMPLIFIED_PRODUCTION_DATABASE='postgres://[username]:[password]@[host]:[port]/[database_name]' \ nypl/circ-scripts

Anchor
_wq87rm9mbm2z _wq87rm9mbm2z

What It Does

...

Once you've given your scripts some time to run (~30 minutes should be enough time to start having works move through the import process), you'll want to refresh your cached materialized views so they show up in your deployed app.```sh$

   $ sudo docker exec circ-scripts /var/www/circulation/core/bin/run refresh_materialized_

...

views

Anchor
_b9bwrvuw3ilv _b9bwrvuw3ilv

Troubleshooting

...

Anchor
_3xw8zwfy5mpu _3xw8zwfy5mpu

Example docker run script

   $ sudo docker run --name circ-

...

webapp \ -d -p 80:80 \ -e SIMPLIFIED_PRODUCTION_DATABASE='postgres://[username]:[password]@[host]:[port]/[database_name]' \ -e SIMPLIFIED_DB_TASK="

...

auto" \ nypl/circ-

...

webapp

Anchor
_5gvpvxf6ewi0 _5gvpvxf6ewi0

What It Does

...

Anchor
_2tm8gnmdm5y1 _2tm8gnmdm5y1

Environment Variables

Anchor
_6kgxy5pl9riu _6kgxy5pl9riu

SIMPLIFIED_CONFIGURATION_FILE

Optional The full path to configuration file in the container. Using the volume options -v, e.g. YOUR_LOCAL_DIRECTORY_WITH_CONFIG_FILE:/etc/simplified, it should look something like -e SIMPLIFIED_CONFIGURATION_FILE=/etc/simplified/YOUR_CONFIGURATION_FILENAME.json.
Use Configuration is now held in the database and accessed via an administrative interface at /admin, so you probably don't need this.
If you do, use this documentation to create the JSON file for your particular library's configuration. If you're unfamiliar with JSON, you can use this JSON Formatter & Validator to validate your configuration file.

Anchor
_eaq7n8qpz3z3 _eaq7n8qpz3z3

SIMPLIFIED_DB_TASK

RequiredOptional. Performs a task against the database at container runtime. Options are:

• ignore : Does nothingauto : Either initializes or migrates the database, depending on if it is new or not. This is the default value.
  
• ignore : Does nothing.
• init : Initializes the app against a brand new database. If you are running a circulation manager for the first time every, use this value to set up an Elasticsearch alias and account for the database schema for future migrations.
• migrate : Migrates an existing database against a new release. Use this value when switching from one stable version to another.

...

Anchor
_5pklaqswpau8 _5pklaqswpau8

SIMPLIFIED_TEST_DATABASE

Optional in v2.x only. The URL of a PostgreSQL database for tests. This optional variable allows unit tests to be run in the container.

Anchor
_u9l543x735gq _u9l543x735gq

TZ

Optional. Scripts container only. The Applies to circ-scripts only. The time zone that cron should use to run scheduled scripts–usually the timezone of the library or libraries on this the circulation manager , selected according instance. This value should be selected according to Debian-system timezone options. This value allows scripts to run at ideal times.

Anchor
_szz2qk9xinew _szz2qk9xinew

Evaluating Success

If your Docker containers are running successfully, you should have a /var/log/simplifieddirectory full of logfiles in your circ-scripts container, and you should be able to visit your server's domain and see an OPDS feed from circ-deploy. If either of these things aren't occurring, use the troubleshooting details above to check var/log/cron.log or the logfiles in /var/log/simplified for circ-scripts and/or /var/log/libsimple/uwsgi.log or /var/log/nginx/error.log.

...

Anchor
_1ovt2xiwqda3 _1ovt2xiwqda3

Elasticsearch

While we do not recommend you run Elasticsearch from a Docker container permanently, you may want to get up and running with a throwaway search index. Elasticsearch isn't installed via the Dockerfile, so the fastest way to connect to it will be through another container. Here's how:

1. Get the Docker image for Elasticsearch v1.x:
2. $ sudo docker pull elasticsearch:1
3. Create an Elasticsearch container, and grab its IP Address. Run, running the following commands:

$ sudo docker run -d --name es elasticsearch:

...

1   # create an elasticsearch container
$ sudo docker

...

ps  # confirm that it's running

...

; note its IP address
$ sudo docker inspect es --format="range .NetworkSettings.Networks.

...

IPAddressend"

1. Add Record the Elasticsearch URL to your configuration filefor use when configuring the Search integration in the Circulation Manager Admin interface. When you run sudo docker ps, you'll see a single running container called es. Use the IP that comes from running inspect to update your your config.json file with the proper Elasticsearch location. You should end up with something like "http://172.17.0.2:9200".

Anchor
_9zl93qfes5pb _9zl93qfes5pb

Postgres

While we do not recommend you run Postgres from a Docker container permanently, you may want to get up and running with a throwaway database. Postgres isn't installed via the Dockerfile, so the best way to connect to Postgres will be through another container. Here's how:

1. Get the Docker image for Postgres 9.4 or 9.5:
2. $ sudo docker pull postgres:9.5
3. Create a Postgres container, and grab its IP Address. Run, running the following commands:

$ sudo docker run -d --name pg postgres:9.

...

5   # create a postgres container
$ sudo docker

...

ps  # confirm that it's running

...

; note its IP address
$ sudo docker inspect pg --format="range .NetworkSettings.Networks.

...

IPAddressend"

1. Create a Postgres database. Run, running the following commands:

$ docker exec -u postgres pg psql -c "create user simplified with password 'test';"  # create a user and password
$ docker exec -u postgres pg psql -c "create database simplified_circ_db;"  # create database
$ docker exec -u postgres pg psql -c "grant all privileges on database simplified_circ_db to simplified;"
$ docker exec -u postgres pg psql -d simplified_circ_db -c "create extension pgcrypto;"

1. Add the Postgres URL to your configuration file. In config.json, add the appropriateproduction_url. You should end up with something like database environment variable as shown above. It will be of the form "postgres://simplified:test@172.17.0.3:5432/simplified_circ_db", following the "postgres://<USERNAME>:<PASSWORD>@<HOST>:<PORT>/<DATABASE_NAME>" format.

...