Backend

The backend itself consists of two major components: a login server and the API server. The login server is a Flask application which handles authentication for the user, generating tokens for the browser’s use when it hits API endpoints. The API server is a Klein application.

Prerequisites

The Python-based backend has a few basic prerequisites:

  • A compatible operating system (we develop on OS X and deploy on Ubuntu)
  • CPython 2.7+ or CPython 3.4+ (we develop and deploy with 2.7 but test against 3.4+)
  • FreeTDS (if using the LANDESK plugin). Installation:
    • With Homebrew on Mac: brew install freetds
    • On Debian-based systems: sudo apt-get install freetds-dev
  • Development headers for libffi. Installation:
    • With Homebrew on Mac: brew install libffi
    • On Debian-based systems: sudo apt-get install libffi-dev

Installation

We recommend using a Python virtualenv. Once you’ve set up an environment for Stethoscope, you can install the backend and the bundled plugins easily using our Makefile:

make develop

Troubleshooting

Python 2.7.6 and pyenv

If installing on OSX 10.10+ for Python 2.7.6 or 2.7.7 using pyenv, you may encounter an error (ld: file not found: python.exe; see this issue) while installing Twisted. The workaround is to build a wheel for Twisted under 2.7.8, then install the wheel into the 2.7.6 environment:

pyenv install 2.7.6
pyenv virtualenv 2.7.6 stethoscope
pyenv install 2.7.8
pyenv shell 2.7.8
pip wheel --wheel-dir=$TMPDIR/wheelhouse Twisted
pyenv shell stethoscope
pip install --no-index --find-links=$TMPDIR/wheelhouse Twisted

Errors installing pymssql

If you encounter a compilation error installing pymssql, you may need to revert to an older version of FreeTDS via:

brew unlink freetds
brew install homebrew/versions/freetds091
pip install pymssql

Configuration

Configuration for the login and API servers is separate, but share the same pattern (a series of .py files loaded via Flask‘s configuration mechanism). In order (last file taking precedence), the configurations are loaded from:

  1. The defaults.py file from the package’s directory (e.g., stethoscope/login/defaults.py).
  2. An ‘instance’ config.py file (in the Flask instance subdirectory, which can be changed using STETHOSCOPE_API_INSTANCE_PATH and STETHOSCOPE_LOGIN_INSTANCE_PATH).
  3. A file specified by the STETHOSCOPE_API_CONFIG or STETHOSCOPE_LOGIN_CONFIG environment variables. Examples of these are in the config/login and config/api subdirectories.

The minimum configuration file needs define only two variables: SECRET_KEY and JWT_SECRET_KEY (see the included instance/config.py file for details).

Testing

The basic tests can be run via the Makefile:

make test

Alternatively, to test against multiple versions of Python, first install tox, then run:

make tox

Running

The backend has two processes which generally need to be running simultaneously: the login server and the API server.

Login

stethoscope-login runserver -p 5002

API

twistd -n web -p 5001 --class=stethoscope.api.resource.resource