SETUP.md 5.34 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
Prerequisites
-------------

* Debian 9
* Python 3.5
* Django 1.11 (included in Python packages below)
* Nginx
* RabbitMQ server
    * Must be accessible at `amqp://guest:guest@localhost:5672//`
    * This can be achieved with just `apt install rabbitmq-server`
* Additional dependencies (Debian package names):
    * `libsasl2-dev`
    * `libldap2-dev`
    * `libssl-dev`
    * `python3-dev`
    * `supervisor`
    * `uwsgi`
    * `uwsgi-emperor`
    * `uwsgi-plugin-python3`
    * `virtualenv`
21
* Python/Django dependencies: see `requirements.txt`
22 23 24 25 26 27 28
* External resources:
    * LDAP database
    * WooCommerce instance
      * [REST API enabled](https://docs.woocommerce.com/document/woocommerce-rest-api/)
      * [WooCommerce Subscriptions](https://woocommerce.com/products/woocommerce-subscriptions/)
      * [JWT Authentication for WP REST API](https://wordpress.org/plugins/jwt-authentication-for-wp-rest-api/)
    * OpenVPN instance (SSH access)
29
      * Including [openvpn-confgen](https://code.puri.sm/purist/openvpn_confgen)
30 31 32 33 34 35 36
      * Typically, the Nginx user (`www-data`) will need SSH access
      * Test with `sudo -u www-data ssh -p PORT REMOTE_USER@HOSTNAME`
      * The user needing access can be changed in
        `purist_middleware_monitor.conf`

Other versions and alternatives may work but are untested.

37 38 39 40 41
Setup
-----

* Install Debian packages (`apt install libsasl2-dev libldap2-dev...`)
* Create installation folders:
David Seaward's avatar
David Seaward committed
42 43 44 45 46
    * `/opt/purist/middleware/` (code)
    * `/opt/purist/middleware_virtualenv/` (Python environment)
    * `/etc/opt/purist/middleware/` (configuration)
    * `/var/opt/purist/middleware/static/` (data and static web files)
    * `/var/log/purist/middleware/` (logs)
47 48 49 50 51
* 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:
David Seaward's avatar
David Seaward committed
52
    * Copy code into `/opt/purist/middleware/`
53 54
    * `chown --recursive www-data:www-data /opt/purist`
* Set up virtualenv:
David Seaward's avatar
David Seaward committed
55 56
    * Create virtualenv (`virtualenv /opt/purist/middleware_virtualenv --python=python3`)
    * `cd /opt/purist/middleware`
57
    * Activate virtualenv (`source ../account_virtualenv/bin/activate`)
58 59
    * Install Python packages (`pip install --requirement requirements.txt`)
    * Confirm packages by comparing `pip freeze` output with `requirements.txt`
60 61
    * Deactivate virtualenv (`deactivate`)
* Complete Django settings:
David Seaward's avatar
David Seaward committed
62 63
    * `cp ./conf/etc/config.ini /etc/opt/purist/middleware/`
    * `cp ./conf/etc/secret.ini /etc/opt/purist/middleware/`
64 65 66 67 68 69 70 71 72 73
    * 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:
David Seaward's avatar
David Seaward committed
74
    * `cp ./config/nginx/purist_middleware /etc/nginx/available_sites/`
75 76
    * Update `server_name` value
    * `cd /etc/nginx/sites-enabled`
David Seaward's avatar
David Seaward committed
77
    * `ln --symbolic ../sites-available/purist_middleware`
78 79
* Hook up uWSGI:
    * `sudo apt install uwsgi uwsgi-emperor uwsgi-plugin-python3`
David Seaward's avatar
David Seaward committed
80
    * `cp ./conf/uwsgi_emperor_vassals/purist_middleware.ini /etc/uwsgi-emperor/vassals/`
81 82
* Hook up Supervisor (supervisord):
    * `sudo apt install supervisor`
David Seaward's avatar
David Seaward committed
83
    * `cp ./conf/supervisord/purist_middleware_monitor.conf /etc/supervisor/conf.d/`
84 85 86 87 88 89 90
* Restart services:
    * `sudo service rabbitmq-server restart`
    * `sudo service uwsgi-emperor restart`
    * `sudo service nginx restart`
    * `sudo service supervisor restart`
* Check logs:
    * `/var/log/nginx/access.log`
91
    * `/var/log/nginx/error.log`
David Seaward's avatar
David Seaward committed
92
    * `/var/log/purist/middleware/beat.log`
93 94 95
    * `/var/log/supervisor/supervisord.log`
    * `/var/log/uwsgi/emperor.log`
    * `/var/log/uwsgi/app/purist_middleware.log`
96 97 98 99

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

100 101 102
Configure
---------

103 104 105 106
* Log in to admin interface as superuser
* Define intervals in Django_Celery_Beat > Intervals
* Define periodic tasks in Django_Celery_Beat > Periodic tasks
* Define known products in Limit Monitor > External bundles
107

108 109 110 111 112
Update
------

* Stop site
* Update packages with `apt update && apt upgrade`
David Seaward's avatar
David Seaward committed
113 114
* Update code in `/opt/purist/middleware/`
* Update settings in `/etc/opt/purist/middleware/`
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145
* 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
-----

See [README.md](README.md)