ojuso-map/README.md

ojuso-map

Kickass map for the Ojuso Project

Getting Started

(These instructions are for GNU/Linux. Running this application on other platforms will probably work.. good luck!)

Check out the code

$ git clone git@gitlab.com:autonomic-cooperative/ojuso-map.git
$ cd ojuso-map

All commands from here on should be run in the ojuso-map directory.

Install System Dependencies

Debian / Ubuntu

$ xargs < system-requirements-debian.txt sudo apt-get install -y

Fedora

$ xargs < system-requirements-fedora.txt sudo dnf install

If you hadn't previously installed Postgres, you will need to initialise the database and start the server:

$ sudo postgresql-setup --initdb --unit postgresql
$ sudo systemctl start postgresql

Set up the Python environment

It is highly recommended to use a Python "virtual environment", which lets you install a separate parallel set of packages for each app you're working on. As an example:

$ pip list | grep Django
$ source .venv/bin/activate
$ pip list | grep Django
Django                    1.11.6 
$ deactivate
$ pip list | grep Django
$ 

See the virtualenv documentation for full instructions

virtualenvwrapper (recommended)

Follow the virtualenvwrapper installation instructions to set it up, then create a new virtual environment and install dependencies in one step with:

$ mkvirtualenv -a . -p /usr/bin/python3 -r requirements-devel.txt ojuso-map

Then, edit the postactivate script:

$ $EDITOR $VIRTUAL_ENV/bin/postactivate

and add a cheeky line to automatically load environment variables (see below):

source `cat $VIRTUAL_ENV/.project`/.env

Manual

Set up your Python virtual environment in the .venv folder:

$ python3 -m venv .venv
$ source .venv/bin/activate

Then install python dependencies:

$ pip3 install --upgrade pip setuptools
$ pip3 install -r requirements-devel.txt

Initialise and load configuration

Copy example.env to .env. If you're using virtualenvwrapper, this file will now be loaded every time you run workon ojuso-map (to reload it after changes, run deactivate && workon ojuso-map). Otherwise, you'll need to load it manually with e.g.

$ source .env

or using direnv (in which case you should call your file .envrc) or autoenv.

Set up database

You need to configure Postgres to allow password (it calls it md5) authentication, and set up a user with superuser privileges on a database.

Follow these instructions to change the Postgres authentication options (NB on Fedora / Centos, pg_hba.conf is located in /var/lib/pgsql/data), then connect to the database:

$ psql -U postgres

(you may need sudo -u postgres psql depending on your security configuration)

Now, either set a password on the postgres user:

postgres=# ALTER USER postgres WITH PASSWORD 'postgres';

or create a new user account and database:

postgres=# CREATE DATABASE ojuso;
postgres=# CREATE USER ojuso WITH PASSWORD 'ojuso'; 
postgres=# ALTER ROLE ojuso SET client_encoding TO 'utf8'; // this is recommended for django
postgres=# ALTER ROLE ojuso SET default_transaction_isolation TO 'read committed'; // so is this
postgres=# GRANT ALL PRIVILEGES on database ojuso to ojuso;
postgres=# ALTER USER ojuso with superuser;  

Type \q to exist the postgres shell.

If you chose the second option, edit your specific database name, username and password into your .env file.

Run The Migrations

$ python manage.py migrate

Start the server

$ python manage.py runserver

(Use Ctrl+C to stop the server)

Resuming work

After shutting down the server / restarting your computer / etc., you will need to run some things to get going again.

With virtualenvwrapper;

$ workon ojuso-map
$ python manage.py runserver

or if you followed "Manual" instructions above:

$ cd ojuso-map
$ source .venv/bin/activate
$ python manage.py runserver

(and $ source .env if you're not using auotenv or direnv)

Running The Tests

You will need to install chromedriver, and if you want to test in Firefox (see comments in ojusomap/tests.py) you will also need to install geckodriver. To install either of these you need to download the zip file for your architecture from http://chromedriver.chromium.org/downloads or https://github.com/mozilla/geckodriver/releases and unzip it into a place on your PATH. Each zip just contains a single binary, so it is very straightforward.

$ pip install -r requirements-test.txt
$ python manage.py collectstatic
$ pytest -v

NB. The "map" tests use selenium with chrome driver, but in headless mode so that they can run in GitLab CI. If you want to see them running, you can comment out the relevant line in ojusomap/tests.py (search for "headless")

Troubleshooting

Sometimes, you see crashes like the following with psycopg:

django.core.exceptions.ImproperlyConfigured: Error loading psycopg2 module:
$USER/.virtualenvs/ojuso-map/lib/python3.6/site-packages/psycopg2/.libs/libresolv-2-c4c53def.5.so:
symbol __res_maybe_init version GLIBC_PRIVATE not defined in file libc.so.6 with
link time reference

In which case the following can help:

$ pip3 uninstall psycopg2 && pip3 install --no-binary :all: psycopg2