README.md 5.42 KB
Newer Older
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.

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:
18 19 20 21
    * `libsasl2-dev`
    * `libldap2-dev`
    * `libssl-dev`
    * `python3-dev`
22
    * `supervisor`
David Seaward's avatar
David Seaward committed
23 24 25 26
* Additional uWSGI packages:
    * `uwsgi`
    * `uwsgi-emperor`
    * `uwsgi-plugin-python3`
David Seaward's avatar
David Seaward committed
27
* Python/Django packages: see `requires/requirements.txt`
28 29 30 31
* External resources:
    * LDAP database
    * WooCommerce instance (REST API)
    * RabbitMQ server
32

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

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

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

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

97 98 99 100 101
Update
------

* Stop site
* Update packages with `apt update && apt upgrade`
David Seaward's avatar
David Seaward committed
102 103
* Update code in `/opt/purist/account/`
* Update settings in `/etc/opt/purist/account/`
104 105 106 107 108 109 110 111 112
* 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

113 114 115
Migrations
----------

116
This is a workaround for [django-ldapdb issue #155](https://github.com/django-ldapdb/django-ldapdb/issues/115).
117 118 119 120 121 122 123

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
124 125
* If you have just added a new LDAP table, switch `NewTable.key` to
  non-primary too
126 127
* Run `migrate`

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

131 132 133
Usage
-----

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

138
Sharing
139 140
-------

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

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

Also includes code portions from:

150 151
* https://github.com/RatanShreshtha/django-registration-templates
  (Copyright 2015 Anders Hofstee and contributors, Expat/MIT)
152 153
* https://github.com/asyd/pyldap_orm/blob/master/pyldap_orm/controls.py
  (Copyright 2016 Bruno Bonfils, Apache 2.0)
154 155
* 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)