ojuso-map/README.md

[![Translation](http://translate.ojuso.org/widgets/platform/-/svg-badge.svg)](http://translate.ojuso.org/engage/platform/?utm_source=widget)
[![pipeline status](https://gitlab.com/autonomic-cooperative/ojuso-map/badges/master/pipeline.svg)](https://gitlab.com/autonomic-cooperative/ojuso-map/commits/master)
[![coverage report](https://gitlab.com/autonomic-cooperative/ojuso-map/badges/master/coverage.svg)](https://gitlab.com/autonomic-cooperative/ojuso-map/commits/master)

# 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

```bash
$ 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

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

### Fedora

```bash
$ 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:

```bash
$ 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:

```bash
$ 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][virtualenv-doc] for full instructions

[virtualenv-doc]: https://virtualenv.pypa.io/en/stable/

### `virtualenvwrapper` (recommended)

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

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

Then, edit the `postactivate` script:

```bash
$ $EDITOR $VIRTUAL_ENV/bin/postactivate
```

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

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

[virtualenvwrapper-install]: https://virtualenvwrapper.readthedocs.io/en/latest/install.html

### Manual

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

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

Then install python dependencies:

```bash
$ 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.

```bash
$ source .env
```

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

[direnv]: https://github.com/direnv/direnv
[autoenv]: https://github.com/kennethreitz/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][postgres authentication] 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:

```bash
$ psql -U postgres
```

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

Now, either set a password on the `postgres` user:

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

or create a new user account and database:

```sql
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.

[postgres authentication]: https://stackoverflow.com/a/51872624/399367

## Run The Migrations

```bash
$ python manage.py migrate
```

## Start the server

```bash
$ 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`;

```bash
$ workon ojuso-map
$ python manage.py runserver
```

or if you followed "Manual" instructions above:

```bash
$ 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.

```bash

$ 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:

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