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

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

# Troubleshooting

If you run into issues with `psycopg2` you may need to run the following:

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