README.md 4.84 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 8 9 10 11 12 13
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/account/>

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

* Debian 8
14 15
* Python 3.4 or 3.5
* Nginx
David Seaward's avatar
David Seaward committed
16
* Additional dependency packages:
David Seaward's avatar
David Seaward committed
17 18 19 20
    * `libsasl2-dev`
    * `libldap2-dev`
    * `libssl-dev`
    * `python3-dev`
David Seaward's avatar
David Seaward committed
21 22 23 24
* Additional uWSGI packages:
    * `uwsgi`
    * `uwsgi-emperor`
    * `uwsgi-plugin-python3`
David Seaward's avatar
David Seaward committed
25
* Python/Django packages: see `requires/requirements.txt`
26
    * Includes Django 1.11
27

28
Other versions and alternatives may work but are untested.
29

David Seaward's avatar
David Seaward committed
30 31
Setup
-----
32

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

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

86 87 88 89 90
Update
------

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

David Seaward's avatar
David Seaward committed
105
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
106 107 108 109 110 111 112

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

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

120 121 122
Usage
-----

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

127
Sharing
128 129
-------

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

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

Also includes code portions from:

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