Skip to content

Latest commit

 

History

History
133 lines (89 loc) · 5.9 KB

README.md

File metadata and controls

133 lines (89 loc) · 5.9 KB
Raw

> The Qabel Index Server

This project provides the index server for Qabel that manages a user directory according to the Qabel Index Protocol.



Introduction | Requirements | Installation

Introduction

For a comprehensive documentation of the whole Qabel Platform use https://qabel.de as the main source of information. http://qabel.github.io/docs/ may provide additional technical information.

Qabel consists of multiple Projects:

Requirements

  • Python 3.5 (+virtualenv)
  • PostgreSQL
  • Mail
  • SMS gateway (e.g. Twilio)

Installation

  1. Bootstrap the project

     $ ./bootstrap.sh
 Run '. ./activate.sh' to activate this environment.
 $ . ./activate.sh
 See 'inv --list' for available tasks.

  2. Create a configuration file (see below), e.g. qabel.yaml

  3. Set settings (see below for details), but most importantly:

    • Change SECRET_KEY and keep it save
    • Change SERVER_PRIVATE_KEY
    • Change database settings according to your needs
    • Configure mail sending
    • Configure the SMS gateway (see below)

  4. Initial deployment

     inv deploy

  5. Point your uWSGI master/emperor at deployed/current/uwsgi.ini

    For example:

     uwsgi --master --http-socket=:9090 /path/to/index/deployed/current/uwsgi.ini

    Or, assuming you have other Qabel servers in /path/to/apps/:

     uwsgi --emperor /path/to/apps/*/deployed/current/uwsgi.ini

    Usually you'd have this as a system-level service though.

Production setup

  • We recommend uWSGI Emperor

  • Add deployed/current/uwsgi.ini as a uWSGI Vassal (this file is created by inv deploy described below).

  • But you can of course also just run it in the normal uWSGI master mode as in

      uwsgi --master /somewhere/qabel-index/deployed/current/uwsgi.ini

  • (Optional) use a webserver of your choice as a proxy (we recommend nginx) if you use a uwsgi UNIX socket.

Django uses Python modules for configuration which is often cumbersome when deploying applications. Therefore we use some scripts based on invoke to handle this automatically. When using these scripts the configuration happens in dedicated YAML configuration files instead.

The search path is:

  • /etc/invoke.yaml, /etc/qabel.yaml
  • ~/.invoke.yaml, ~/.qabel.yaml
  • ./invoke.yaml, ./qabel.yaml

The default configuration (defaults.yaml) contains an overview of the settings needed in a production setup.

Also see the django documentation for a checklist of settings you need to revisit for deployment.

Also see the full list of django core options, especially about databases.

The server exports prometheus metrics at /metrics. If those should not be public, you should block this location in the webserver.

If you have problems with CORS (Cross-Origin Resource Sharing), edit the 'CORS_ORIGIN_WHITELIST' in the configuration. For more information see [CORS middleware configuration options](https://github .com/zestedesavoir/django-cors-middleware#configuration).

manage.py commands in production are run with inv manage instead of python manage.py. Note that the former requires quotes around the command line:

inv manage 'check --deploy'

Also note that changes in configuration are (on purpose) not reflected in the inv manage environment until you ran inv deploy to actually deploy them.

Finally, after writing a configuration file, it is time to deploy (note that this step requires the database settings to be correct, and the database to be available, since inv deploy also runs any database up/downgrades that may be necessary):

inv deploy

Done. If a bad commit is deployed roll it back:

inv deploy --commit <known good commit>

deployed/deploy-history keeps track of which commits where deployed when if you are in doubt.

There is also support for multiple concurrent deployments for e.g. blue/green deployments: inv deploy --into green would deploy the application into deployed/green/uwsgi.ini.

Running the tests

$ py.test (that's it)