README.md 4.95 KB
Newer Older
David Seaward's avatar
David Seaward committed
1 2
Purist account manager
======================
3

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

David Seaward's avatar
David Seaward committed
8
Expects to be hosted at <https://example.com>
9 10 11 12 13

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

* Debian 8
14
* Python 3.4 or 3.5
15
* Django 1.11 (included in Python packages below)
16
* Nginx
David Seaward's avatar
David Seaward committed
17
* Additional dependency packages:
David Seaward's avatar
David Seaward committed
18 19 20 21
    * `libsasl2-dev`
    * `libldap2-dev`
    * `libssl-dev`
    * `python3-dev`
David Seaward's avatar
David Seaward committed
22 23 24 25
* Additional uWSGI packages:
    * `uwsgi`
    * `uwsgi-emperor`
    * `uwsgi-plugin-python3`
David Seaward's avatar
David Seaward committed
26
* Python/Django packages: see `requires/requirements.txt`
27 28 29 30
* External resources:
    * LDAP database
    * WooCommerce instance (REST API)
    * RabbitMQ server
31

32
Other versions and alternatives may work but are untested.
33

David Seaward's avatar
David Seaward committed
34 35
Setup
-----
36

David Seaward's avatar
David Seaward committed
37 38
* Install Debian packages (`apt install libsasl2-dev libldap2-dev...`)
* Create installation folders:
David Seaward's avatar
David Seaward committed
39
    * `/opt/purist/account/` (code)
David Seaward's avatar
David Seaward committed
40
    * `/opt/purist/account_virtualenv/` (Python environment)
David Seaward's avatar
David Seaward committed
41 42 43
    * `/etc/opt/purist/account/` (configuration)
    * `/var/opt/purist/account/static/` (data and static web files)
    * `/var/log/purist/account/` (logs)
David Seaward's avatar
David Seaward committed
44 45 46 47 48 49 50 51 52 53 54
* 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`)
55
    * Install Python packages (`pip install --requirement requires/requirements.txt`)
David Seaward's avatar
David Seaward committed
56 57 58
    * Confirm packages by comparing `pip freeze` output with `requires/requirements.txt`
    * Deactivate virtualenv (`deactivate`)
* Complete Django settings:
David Seaward's avatar
David Seaward committed
59 60
    * `cp ./conf/etc/config.ini /etc/opt/purist/account/`
    * `cp ./conf/etc/secret.ini /etc/opt/purist/account/`
61
    * Fill in settings
David Seaward's avatar
David Seaward committed
62 63 64 65 66
* Run initial setup:
    * Activate virtualenv (`source ../account_virtualenv/bin/activate`)
    * `./manage.py collectstatic`
    * `./manage.py migrate`
    * `./manage.py createsuperuser`
67 68
    * When prompted, enter the credentials of your LDAP superuser /
      account manager
David Seaward's avatar
David Seaward committed
69 70
    * Deactivate virtualenv (`deactivate`)
* Hook up Nginx:
71
    * `cp ./config/nginx/purist_account /etc/nginx/available_sites/`
David Seaward's avatar
David Seaward committed
72 73 74 75 76 77 78 79 80 81 82 83 84 85
    * 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/`
* Restart services:
    * `sudo service uwsgi-emperor restart`
    * `sudo service nginx 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`
86

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

90 91 92 93 94
Update
------

* Stop site
* Update packages with `apt update && apt upgrade`
David Seaward's avatar
David Seaward committed
95 96
* Update code in `/opt/purist/account/`
* Update settings in `/etc/opt/purist/account/`
97 98 99 100 101 102 103 104 105
* 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

David Seaward's avatar
David Seaward committed
106 107 108
Migrations
----------

David Seaward's avatar
David Seaward committed
109
This is a workaround for [django-ldapdb issue #155](https://github.com/django-ldapdb/django-ldapdb/issues/115).
David Seaward's avatar
David Seaward committed
110 111 112 113 114 115 116

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
117 118
* If you have just added a new LDAP table, switch `NewTable.key` to
  non-primary too
David Seaward's avatar
David Seaward committed
119 120
* Run `migrate`

121 122
You only need to do this when creating new migrations (`makemigrations`)
not when running existing migrations (`migrate`).
David Seaward's avatar
David Seaward committed
123

124 125 126
Usage
-----

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

131
Sharing
132 133
-------

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

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

Also includes code portions from:

143 144
* https://github.com/RatanShreshtha/django-registration-templates
  (Copyright 2015 Anders Hofstee and contributors, Expat/MIT)
145 146
* https://github.com/asyd/pyldap_orm/blob/master/pyldap_orm/controls.py
  (Copyright 2016 Bruno Bonfils, Apache 2.0)