Overview

For a general overview of the PREMIS Event Service, please see the project README.rst file (included below for convenience).

PREMIS Event Service

https://travis-ci.org/unt-libraries/django-premis-event-service.svg?branch=master

PREMIS Event Service is a Django application for managing PREMIS Events in a structured, centralized, and searchable manner.

Purpose

The purpose of this application is to provide a straightforward way to send PREMIS-formatted events to a central location to be stored and retrieved. In this fashion, it can serve as an event logger for any number of services that happen to wish to use it. PREMIS is chosen as the underlying format for events due to its widespread use in the digital libraries world.

Dependencies

  • Python 2.7+ (not Python 3)
  • Django (tested on 1.7-1.10; 1.3 or higher required)
  • lxml (requires libxml2-dev to be installed on your system)

Documentation

Documentation, including installation instructions, can be viewed online at:

http://premis-event-service.readthedocs.org/

The documentation is also browsable locally from within the docs directory of this repository. You can read the source files in plain text from the docs/source directory, or generate your own local copy of the HTML files by doing the following:

  1. Make sure Sphinx is installed (pip install sphinx)
  2. cd docs
  3. make html
  4. Open index.html (generated in docs/build/html)

License

See LICENSE.

Acknowledgements

The Premis Event Service was developed at the UNT Libraries and has been worked on by a number of developers over the years including

  • Kurt Nordstrom
  • Joey Liechty
  • Lauren Ko
  • Stephen Eisenhauer
  • Mark Phillips
  • Damon Kelley
  • Reed Underwood

If you have questions about the project feel free to contact Mark Phillips at mark.phillips@unt.edu

Developing

There are two (supported) ways to develop the PREMIS event service Django app. One is natively using an SQLite backend. The other is using a MySQL backend for storage inside a Docker container.

Developing Natively Using SQLite

Clone the repository
$ git clone https://github.com/unt-libraries/django-premis-event-service.git # check the repo for the latest official release if you don't want the development version at HEAD on the master branch
$ cd django-premis-event-service
Create a virtualenv environment
$ mkvirtualenv premis-event-service # to create and enter the virtualenv
(premis-event-service) $ deactivate # to exit the virtualenv
$ workon premis-event-service # to reactivate the virtualenv
Install the requirements using pip
(premis-event-service) $ pip install -r requirements.txt # install dependencies from text file
Run the tests using tox
(premis-event-service) $ tox

Note that the tests will be run in multiple environments, most importantly in distinct environments for Django major versions 1.7-1.10. Tests will also be run against the Django master branch, which is a development branch and prone to failure. These failures are ignored by the PREMIS Event Service testing configuration, and you can likely ignore them as well, particularly if you are using one of the other Django major versions against which the tests should pass.

Apply the migrations
(premis-event-service) $ python manage.py migrate
Start the development server
(premis-event-service) $ python manage.py runserver 9999

This will start the development server listening locally on port 9999. You may want to change the port number, passed as the first argument to the runserver command.

View the web UI in a browser

Navigate to http://localhost:9999/event/ (or whatever port you chose) to see the UI of the app.

Developing Using Docker and MySQL as a Backend

Install Docker

On Debian-derived Linux distros, you can use apt-get to install. If you’re on a different OS, check the Docker site for instructions.

Install Docker Compose
$ pip install docker-compose

Alternatively, you may want to install docker-compose using your system’s package manager.

Clone the repository
$ git clone https://github.com/unt-libraries/django-premis-event-service.git # check the repo for the latest official release if you don't want the development version at HEAD on the master branch
$ cd django-premis-event-service
Starting the app
# start the app
$ docker-compose up -d db app

# optional: add a superuser in order to login to the admin interface
$ docker-compose run manage createsuperuser
View the web UI in a browser

Navigate to http://localhost:8000/event/ to see the UI of the app. The port can be changed by editing the docker-compose.yml file.

The code is in a volume that is shared between your workstation and the app container, which means any edits you make on your workstation will also be reflected in the Docker container. No need to rebuild the container to pick up changes in the code.

However, if the requirements files change, it is important that you rebuild the app container for those packages to be installed. This is something that could happen when switching between feature branches, or when pulling updates from the remote.

# stop the app
$ docker-compose stop

# remove the app container
$ docker-compose rm app

# rebuild the app container
$ docker-compose build app # under some circumstances, you may need to use the --no-cache switch, e.g. upstream changes to packages the app requires

# start the app
$ docker-compose up -d db app
Viewing the logs
$ docker-compose logs -f
Running the Tests

To run the tests via Tox, use this command.

$ docker-compose run --rm app test