On this page:

• Glossary
• Installation
• Typical usage
• Notes for those of us who don't know Django

Glossary

Note: Over the course of the project, the terminology has changed, with the result that different areas of the codebase use different names for the same concepts.

While we aspire to eventually to update for consistency, in the meantime, these three terms listed below are used interchangeably in code. The first listed option (in bold) is the one currently used by the project, and the term used in the database is indicated by db:

• source / citation db
  The document that contains the Records. A Source includes bibliographic information (e.g. author, title, ...)
• record / item / reference db
  The bit of text within the Source that describes a group of Referents (references to people) as well as an event or situation with date, location, etc. Typical Record types include self-emancipation notices (aka "Escape Slave ads") or a single baptismal record
• referent db / person / entrant
  A reference to a person contained in a Record. Note that we reserve the term Person to indicate a particular individual. There may be multiple references to the same Person across different Records, and therefore there may be multiple Referents that in fact are the same Person

Installation

(Assumes Docker is installed and running.)

• Create a local "stuff" directory (name it anything) -- and from your terminal, cd into it (one-time step)

From the terminal, run:

• git clone git@github.com:Brown-University-Library/stolen_relations_start_data.git
  (a one-time step; downloads the login/password security information for the input form)
• git clone --depth 1 git@github.com:Brown-University-Library/sr_dkr_sql-database.git
  (a one-time step; downloads the SR mySQL database)
• git clone git@github.com:Brown-University-Library/sr_input_form.git
  (a one-time step; downloads the SR input form codebase)
• cd sr_input_form
  Sets the current directory to sr_input_form
• docker-compose up
  Creates the container (which starts the webapp)

The webapp should be running; from a browser, go to http://127.0.0.1:8000/version/ or http://127.0.0.1:8000/login/.

If you want to tinker with the database via the database manager adminer, go to http://127.0.0.1:8080.

Typical usage

• cd <SOME_PATH>/sr_input_form
  Sets the current directory to sr_input_form
• docker-compose up
  Creates the container (which starts the webapp)

Note: if a code-update installs a new python-package, either:

• delete the sr\_input\_form-web image which should force it to be rebuilt (best option), or...
• run docker-compose up --build to force the container to be rebuilt. (I don't think this actually creates a new image, so subsequent runs of docker-compose up will still use the old image.)

Notes for those of us who don't know Django

Some critical files:

sr_input_form/config/settings.py

Django settings for sr_input_form. Mostly "where are things" and security keys, etc.

Generated by 'django-admin startproject' using Django 1.11.

More information on this file

Full list of settings and their values

sr_input_form/config/urls.py

Maps URL patterns to views, e.g.:

url( r'^editor/documents/(?P<cite_id>.*)/$', views.edit_citation, name='edit_citation_url' )

which maps to the function definition in sr_input_form/disa_app/views.py:

@shib_login
def edit_citation( request, cite_id=None ):

sr_input_form/disa_app/admin.py

Seems to extend administrative functions, and handles the "marked for deletion" system. Contains 3 class definitions:

• MarkedForDeletionAdminForm
• UserProfileAdmin
• MarkedForDeletionAdmin

sr_input_form/disa_app/disa_app_templates

The templates for the public pages. These files are referenced in disa_app/views.py.

sr_input_form/disa_app/lib

A bunch of Stolen Relations-specific python code. This seems to be the main code area.

Includes:

• generate_browse_data.py
• a bunch of view_*_manager.py

sr_input_form/disa_app/models_sqlalchemy.py

Model definition for SQL Alchemy

sr_input_form/disa_app/models.py

Not sure (ask Birkin)

sr_input_form/disa_app/settings_app.py

Some random settings—authentication, DB location, etc. Not sure how this relates to sr_input_form/config/settings.py

sr_input_form/disa_app/views.py

A bunch of routines that are called by sr_input_form/config/urls.py and reference sr_input_form/disa_app/disa_app_templates.