SETUP.md 5.15 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
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`
* Python/Django dependencies: see `requires/requirements.txt`
* 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/)
        (pending)
    * OpenVPN instance (SSH access)
      * Including [openvpn-confgen](https://plan.puri.st/module/openvpn_confgen)
      * 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.

38 39 40 41 42
Setup
-----

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

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`
David Seaward's avatar
David Seaward committed
106 107
* Update code in `/opt/purist/middleware/`
* Update settings in `/etc/opt/purist/middleware/`
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138
* 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)