================
encyc-rg Setup
================

This page documents the process of installing and configuring `encyc-rg` on an existing Debian Linux machine.

Most of the commands you will type will be entered as `root`.  To become `root`, type the following at a command prompt::

    $ su - root
    [enter root password]

As per convention, variables in this documentation are written in upper case with underscores, starting with a "$" sign.


Install From Package Repository
===============================

Add package repository and install packages.
::
    $ sudo apt-get update && sudo apt-get install curl apt-transport-https gnupg
    $ sudo curl -s http://packages.densho.org/debian/keys/archive.asc | sudo apt-key add -
    $ echo "deb http://packages.densho.org/debian/ jessie main" | sudo tee /etc/apt/sources.list.d/packages_densho_org_debian.list
    $ sudo apt-get update && sudo apt-get install encycrg-master

Once packages are installed you can upgrade to newer versions thusly
::
    $ sudo apt-get update && sudo apt-get upgrade


Install From Package File
=========================

You can install from a `.deb` package file.  Note that with this method you will not receive automatic updates via `apt-get upgrade`.
::
    $ sudo apt-get install gdebi-core
    $ sudo gdebi install encycrg-BRANCH_VERSION~deb8_amd64.deb


Install From Source
===================

::
    $ sudo su -
    # apt-get install git-core
    # git clone git@github.com:densho/encyc-rg.git /opt/encyc-rg
    # cd /opt/encyc-rg/encycrg
    # If you are testing a branch, switch to that branch.
    # git checkout -b BRANCHNAME origin/BRANCHNAME
    # make install
    
By default the app will run under `supervisor`::

    # supervisor restart encycrg
    # supervisor stop encycrg
    # supervisor status
    
To use the Django dev server, stop `supervisor` and open a new tab::

    # su encyc
    $ cd /opt/encyc-rg
    $ source /opt/encyc-rg/venv/encycrg/bin/activate
    $ python encycrg/manage.py runserver 0.0.0.0:8081


Configuration
=============

The default settings in `/etc/encyc/rg.cfg` are specific to the Densho production system.  Settings in `/etc/encyc/rglocal.cfg` will override the defaults.

Edit `/etc/encyc/rglocal.cfg` to include the following text.::

    [public]
    
    # Absolute path to directory that will hold static and user-uploaded files.
    # Note: Should match MEDIA_ROOT and STATIC_ROOT in Makefile.
    # Note: Should not have trailing slashes.
    static_root=/var/www/encycrg/static
    media_root=/var/www/encycrg/media

To get the nice Django error messages edit `/opt/encyc-rg/encycrg/encycrg/settings.py`.  **WARNING: setting `DEBUG = True` in a production environment is a security risk!**::

    DEBUG = True
    THUMBNAIL_DEBUG = False

`encyc-rg` uses the Django ORM to store data about locally-created thumbnail images in a SQLite3 database.  Create database tables for installed applications.::

    # make syncdb

Restart the servers and the web application to see the effects of your edits.::

    # make restart

At this point `encyc-rg` is installed but the Elasticsearch database contains no data.


Making Packages
===============

For a totally fresh package, or when switching branches, remove the virtualenv and start fresh.
::
    # rm -Rf venv
    # make install

Make packages for deb8 and deb9.
::
    # make deb

At this point you have .deb packages for one or more Debian versions (e.g. deb8/Jessie, deb9/Stretch) that you can upload to a package repository or use to install on any Debian system of the corresponding version.

Packages are named thusly::

    encycrg-BRANCH_VERSION~deb8_amd64.deb
    encycrg-BRANCH_VERSION~deb9_amd64.deb


Publishing Packages
===================

Packages are deployed using reprepro, a tool for managing Debian-style package repositories.  See operations manual for location of the repository.  SSH in to the repository server as the `reprepro` user (it will not work to log in as another user and become `reprepro` user via `sudo su -`).  once logged in, run the following to ingest the packages into the repository.
::
    # Debian 8 / Jessie
    $ cp encycrg-BRANCH_VERSION~deb8_amd64.deb incoming/
    $ reprepro-ingest -c /etc/reprepro.conf jessie
    # Debian 9 / Stretch
    $ cp encycrg-BRANCH_VERSION~deb9_amd64.deb incoming/
    $ reprepro-ingest -c /etc/reprepro.conf stretch

At this point you can install the app as per Install From Package Repository above.