Installation

This is a draft
This documentation is in an early state and your mileage may vary, please raise issues on github for any problems you encounter.

From pip

pip install orlo

The pip build will usually be up to date, but occasionally it may be behind, especially relative to development forks.

From source

Clone the github repo:

git clone https://github.com/eBayClassifiedsGroup/orlo.git
cd orlo
python setup.py install

Or:

pip install https://github.com/eBayClassifiedsGroup/orlo.git

Developing in Vagrant

Install Vagrant as per the docs, cd to the git clone of orlo and run vagrant up.

From here you should be able to do cd /vagrant/orlo followed by python setup.py develop.

Tests can be run with tox.

Building the debian package

This is not as nice as it could be at present but will improve in future. The main problem is that dh-virtualenv as supplied in jessie is too old, so you will need to obtain a version > 0.9. For this I suggest the repo provided by the author: https://launchpad.net/~spotify-jyrki/+archive/ubuntu/dh-virtualenv

Other than that, the vagrant environment is mostly setup to do this, so I suggest starting from there.

The debian packages you will need (already installed by Vagrant) are:

sudo apt-get -y install python-pip python-dev postgresql postgresql-server-dev-all build-essential git-buildpackages debhelper python-dev

(plus dh-virtualenv)

It should work on Ubuntu 14.04 and Debian Jessie onwards.

From there, cd into a copy of the orlo repo and run make deb.

If you have made changes beforehand, it is a good idea to update the version in setup.py and run make changelog first so that your package is distinct from any that we release. You will need to have git configured for this (git-dch will tell you on invocation).

Initial Configuration

Orlo provides a command line interface for performing actions such as writing the config, setting up the database and running a test server. Run orlo –help for more information.

On first install, you will want to write out a config file:

sudo orlo write_config

Once setup, you can run the server with systemctl start orlo if you used the debian package, or orlo runserver if you installed with pip.

Database setup

Orlo uses SQLAlchemy ORM which can use many database backends, but our instances use Postgres. Tests are run against in-memory SQLite, thus for small deploys sqlite should be fine, but you may run into problems with concurrent users. We strongly suggest setting up a proper database such as postgres.

Postgres

sudo -u postgres -i
psql

From the psql prompt:

postgres=# create user orlo with password 'my-secure-password';
CREATE ROLE
postgres=# create database orlo owner orlo;
CREATE DATABASE
postgres=#

Update uri under [db] in orlo.ini, e.g.

uri = postgres://orlo:my-secure-password@localhost:5432/orlo

SQLite

Create a directory for the db, e.g. :

mkdir /var/lib/orlo
chown orlo:root /var/lib/orlo

Update the uri under [db] in orlo.ini to point to a file in this directory:

uri = sqlite:///var/lib/orlo/database.sqlite

Both

If installed from the debian package run

orlo setup_database

Running under Gunicorn

Under ./etc an example systemd unit file is provided, but to run it in the foreground with 4 workers do:

gunicorn -w 4 -b 127.0.0.1:8080 orlo:app

Test it is running:

curl -v 127.0.0.1:8080/ping

And it should return ‘pong’

Nginx Setup

We strongly recommend running orlo behind a proxy such as nginx, with TLS if you plan to use authentication. An example configuration is provided under ./etc/