Purist account manager
======================

A Django site for account registration and management for Purist
services. In particular, user registration creates an LDAP user,
which is used for authentication by other services.

Expects to be hosted at <https://example.com>

Prerequisites
-------------

* Debian 8
* Python 3.4 or 3.5
* Django 1.11 (included in Python packages below)
* Nginx
* Additional dependency packages:
    * `libsasl2-dev`
    * `libldap2-dev`
    * `libssl-dev`
    * `python3-dev`
    * `supervisor`
* Additional uWSGI packages:
    * `uwsgi`
    * `uwsgi-emperor`
    * `uwsgi-plugin-python3`
* Python/Django packages: see `requires/requirements.txt`
* External resources:
    * LDAP database
    * WooCommerce instance (REST API)
    * RabbitMQ server

Other versions and alternatives may work but are untested.

Setup
-----

* Install Debian packages (`apt install libsasl2-dev libldap2-dev...`)
* Create installation folders:
    * `/opt/purist/account/` (code)
    * `/opt/purist/account_virtualenv/` (Python environment)
    * `/etc/opt/purist/account/` (configuration)
    * `/var/opt/purist/account/static/` (data and static web files)
    * `/var/log/purist/account/` (logs)
* Populate brand data (if it doesn't already exist):
    * Create `/var/opt/purist/brand/` (shared data and static web files)
    * Populate `brand` folder
    * `chown --recursive www-data:www-data /var/opt/purist`
* Copy project code:
    * Copy code into `/opt/purist/account/`
    * `chown --recursive www-data:www-data /opt/purist`
* Set up virtualenv:
    * Create virtualenv (`virtualenv /opt/purist/account_virtualenv --python=python3`)
    * `cd /opt/purist/account`
    * Activate virtualenv (`source ../account_virtualenv/bin/activate`)
    * Install Python packages (`pip install --requirement requires/requirements.txt`)
    * Confirm packages by comparing `pip freeze` output with `requires/requirements.txt`
    * Deactivate virtualenv (`deactivate`)
* Complete Django settings:
    * `cp ./conf/etc/config.ini /etc/opt/purist/account/`
    * `cp ./conf/etc/secret.ini /etc/opt/purist/account/`
    * Fill in settings
* Run initial setup:
    * Activate virtualenv (`source ../account_virtualenv/bin/activate`)
    * `./manage.py collectstatic`
    * `./manage.py migrate`
    * `./manage.py createsuperuser`
    * When prompted, enter the credentials of your LDAP superuser /
      account manager
    * Deactivate virtualenv (`deactivate`)
* Hook up Nginx:
    * `cp ./config/nginx/purist_account /etc/nginx/available_sites/`
    * Update `server_name` value
    * `cd /etc/nginx/sites-enabled`
    * `ln --symbolic ../sites-available/purist_account`
* Hook up uWSGI:
    * `sudo apt install uwsgi uwsgi-emperor uwsgi-plugin-python3`
    * `cp ./conf/uwsgi_emperor_vassals/purist_account.ini /etc/uwsgi-emperor/vassals/`
* Hook up Supervisor (supervisord):
    * `sudo apt install supervisor`
    * `cp ./conf/supervisord/purist_account_monitor.conf /etc/supervisor/conf.d/`
* Restart services:
    * `sudo service uwsgi-emperor restart`
    * `sudo service nginx restart`
    * `sudo service supervisor restart`
* Check logs:
    * `/var/log/uwsgi/emperor.log`
    * `/var/log/uwsgi/app/purist_account.log`
    * `/var/log/nginx/error.log`
    * `/var/log/nginx/access.log`
    * `/var/log/supervisor/supervisord.log`
    * `/var/log/purist/account/beat.log`

For more options and details see
<https://docs.djangoproject.com/en/1.11/#the-development-process>

Update
------

* Stop site
* Update packages with `apt update && apt upgrade`
* Update code in `/opt/purist/account/`
* Update settings in `/etc/opt/purist/account/`
* Update virtualenv:
    * Activate virtualenv (`./bin/activate.py`)
    * Update Python packages (`pip install  --requirement requires/requirements.txt`)
    * Do not use `pip install --update` as this will not respect requirements
* Update site:
    * Run `./manage.py collectstatic`
    * Run `./manage.py migrate` (see **Migrations** below)
* Start site

Migrations
----------

This is a workaround for [django-ldapdb issue #155](https://github.com/django-ldapdb/django-ldapdb/issues/115).

If you need to make a new migration:

* Open `ldapregister.0003_ldapgroup_ldapperson`
* Switch `LdapGroup.cn` and `LdapPerson.uid` from non-primary to primary
* Run `makemigrations`
* Switch `LdapGroup.cn` and `LdapPerson.uid` back to non-primary
* If you have just added a new LDAP table, switch `NewTable.key` to
  non-primary too
* Run `migrate`

You only need to do this when creating new migrations (`makemigrations`)
not when running existing migrations (`migrate`).

Usage
-----

* Start Django site as system service, or with `./manage.py runserver`
* Visit <https://example.com/account> and follow login and/or
  registration links

Sharing
-------

Purist account manager, for registration and account management <br />
Copyright 2017 Purism SPC and contributors <br />
SPDX-License-Identifier: GPL-3.0+

Shared under GPLv3-or-later, see [COPYING.md](COPYING.md) for details.
Contributions under the same terms are welcome.

Also includes code portions from:

* https://github.com/RatanShreshtha/django-registration-templates
  (Copyright 2015 Anders Hofstee and contributors, Expat/MIT)
* https://github.com/asyd/pyldap_orm/blob/master/pyldap_orm/controls.py
  (Copyright 2016 Bruno Bonfils, Apache 2.0)
* https://github.com/celery/celery/blob/master/extra/supervisord/celerybeat.conf
  (Copyright 2009-2012, 2015-2016 Ask Solem and contributors, 2012-2014 GoPivotal, Inc, BSD 3-Clause)