2017-10-06 18:15:28 +00:00
|
|
|
[![Translation](http://translate.ojuso.org/widgets/platform/-/svg-badge.svg)](http://translate.ojuso.org/engage/platform/?utm_source=widget)
|
2018-04-12 19:25:46 +00:00
|
|
|
[![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
|
2017-10-06 18:15:28 +00:00
|
|
|
|
2017-05-18 15:20:15 +00:00
|
|
|
Kickass map for the Ojuso Project
|
2018-04-08 20:22:31 +00:00
|
|
|
|
2018-04-12 19:25:46 +00:00
|
|
|
# Getting Started
|
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
(These instructions are for GNU/Linux. Running this application on other
|
|
|
|
platforms will probably work.. good luck!)
|
|
|
|
|
2018-09-05 15:33:25 +00:00
|
|
|
## 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.
|
|
|
|
|
2018-04-12 19:25:46 +00:00
|
|
|
## Install System Dependencies
|
2018-04-08 20:22:31 +00:00
|
|
|
|
2018-09-05 15:33:25 +00:00
|
|
|
### Debian / Ubuntu
|
2018-05-19 17:47:30 +00:00
|
|
|
|
2018-04-08 20:22:31 +00:00
|
|
|
```bash
|
2018-09-05 15:33:25 +00:00
|
|
|
$ xargs < system-requirements-debian.txt sudo apt-get install -y
|
2018-04-08 20:22:31 +00:00
|
|
|
```
|
|
|
|
|
2018-05-19 17:47:30 +00:00
|
|
|
### Fedora
|
|
|
|
|
|
|
|
```bash
|
2018-09-05 15:33:25 +00:00
|
|
|
$ 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
|
2018-09-05 15:35:07 +00:00
|
|
|
$ sudo postgresql-setup --initdb --unit postgresql
|
|
|
|
$ sudo systemctl start postgresql
|
2018-09-05 15:33:25 +00:00
|
|
|
```
|
2018-04-12 19:25:46 +00:00
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
## Set up the Python environment
|
2018-04-12 19:25:46 +00:00
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
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:
|
2018-04-12 19:25:46 +00:00
|
|
|
|
|
|
|
```bash
|
2018-09-23 02:47:35 +00:00
|
|
|
$ pip list | grep Django
|
2018-09-05 15:33:25 +00:00
|
|
|
$ source .venv/bin/activate
|
2018-09-23 02:47:35 +00:00
|
|
|
$ pip list | grep Django
|
|
|
|
Django 1.11.6
|
|
|
|
$ deactivate
|
|
|
|
$ pip list | grep Django
|
|
|
|
$
|
2018-04-12 19:25:46 +00:00
|
|
|
```
|
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
See the [virtualenv documentation][virtualenv-doc] for full instructions
|
2018-09-10 16:23:40 +00:00
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
[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:
|
2018-04-12 19:25:46 +00:00
|
|
|
|
|
|
|
```bash
|
2018-09-23 02:47:35 +00:00
|
|
|
$ mkvirtualenv -a . -p /usr/bin/python3 -r requirements-devel.txt ojuso-map
|
2018-04-12 19:25:46 +00:00
|
|
|
```
|
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
Then, edit the `postactivate` script:
|
2018-04-12 19:25:46 +00:00
|
|
|
|
|
|
|
```bash
|
2018-09-23 02:47:35 +00:00
|
|
|
$ $EDITOR $VIRTUAL_ENV/bin/postactivate
|
2018-04-12 19:25:46 +00:00
|
|
|
```
|
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
and add a cheeky line to automatically load environment variables (see below):
|
2018-04-12 19:25:46 +00:00
|
|
|
|
|
|
|
```bash
|
2018-09-23 02:47:35 +00:00
|
|
|
source `cat $VIRTUAL_ENV/.project`/.env
|
2018-04-12 19:25:46 +00:00
|
|
|
```
|
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
[virtualenvwrapper-install]: https://virtualenvwrapper.readthedocs.io/en/latest/install.html
|
2018-09-10 16:23:40 +00:00
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
### Manual
|
2018-09-05 15:33:25 +00:00
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
Set up your Python virtual environment in the `.venv` folder:
|
2018-09-05 15:33:25 +00:00
|
|
|
|
|
|
|
```bash
|
2018-09-23 02:47:35 +00:00
|
|
|
$ python3 -m venv .venv
|
|
|
|
$ source .venv/bin/activate
|
2018-09-05 15:33:25 +00:00
|
|
|
```
|
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
Then install python dependencies:
|
2018-04-12 19:25:46 +00:00
|
|
|
|
2018-09-05 15:33:25 +00:00
|
|
|
```bash
|
2018-09-23 02:47:35 +00:00
|
|
|
$ pip3 install --upgrade pip setuptools
|
|
|
|
$ pip3 install -r requirements-devel.txt
|
2018-04-12 19:25:46 +00:00
|
|
|
```
|
2018-09-05 15:33:25 +00:00
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
## Initialise and load configuration
|
2018-09-10 16:23:40 +00:00
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
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.
|
2018-09-10 16:23:40 +00:00
|
|
|
|
|
|
|
```bash
|
2018-09-23 02:47:35 +00:00
|
|
|
$ source .env
|
2018-09-10 16:23:40 +00:00
|
|
|
```
|
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
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
|
2018-09-10 16:23:40 +00:00
|
|
|
```
|
2018-09-23 02:47:35 +00:00
|
|
|
|
|
|
|
(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';
|
2018-09-10 16:23:40 +00:00
|
|
|
```
|
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
or create a new user account and database:
|
2018-09-10 16:23:40 +00:00
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
```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;
|
2018-09-10 16:23:40 +00:00
|
|
|
```
|
2018-09-23 02:47:35 +00:00
|
|
|
|
2018-09-10 16:23:40 +00:00
|
|
|
Type `\q` to exist the postgres shell.
|
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
If you chose the second option, edit your specific database name, username and
|
|
|
|
password into your `.env` file.
|
2018-09-10 16:23:40 +00:00
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
[postgres authentication]: https://stackoverflow.com/a/51872624/399367
|
2018-09-10 16:23:40 +00:00
|
|
|
|
2018-09-05 15:33:25 +00:00
|
|
|
## Run The Migrations
|
|
|
|
|
|
|
|
```bash
|
2018-04-12 19:47:40 +00:00
|
|
|
$ python manage.py migrate
|
2018-04-12 19:25:46 +00:00
|
|
|
```
|
|
|
|
|
2018-09-05 15:33:25 +00:00
|
|
|
## Start the server
|
|
|
|
|
|
|
|
```bash
|
|
|
|
$ python manage.py runserver
|
|
|
|
```
|
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
(Use `Ctrl+C` to stop the server)
|
|
|
|
|
2018-09-05 15:33:25 +00:00
|
|
|
# Resuming work
|
2018-04-12 19:25:46 +00:00
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
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:
|
2018-09-05 15:33:25 +00:00
|
|
|
|
|
|
|
```bash
|
|
|
|
$ cd ojuso-map
|
|
|
|
$ source .venv/bin/activate
|
|
|
|
$ python manage.py runserver
|
|
|
|
```
|
|
|
|
|
2018-09-23 02:47:35 +00:00
|
|
|
(and `$ source .env` if you're not using `auotenv` or `direnv`)
|
|
|
|
|
2018-09-05 15:33:25 +00:00
|
|
|
# Running The Tests
|
|
|
|
|
|
|
|
```bash
|
2018-05-01 17:30:42 +00:00
|
|
|
$ pip install -r requirements-test.txt
|
2018-09-23 02:47:35 +00:00
|
|
|
$ python manage.py collectstatic
|
2018-04-12 19:25:46 +00:00
|
|
|
$ pytest -v
|
|
|
|
```
|
2018-09-23 02:47:35 +00:00
|
|
|
|
|
|
|
# Troubleshooting
|
|
|
|
|
2018-09-23 21:04:22 +00:00
|
|
|
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:
|
2018-09-23 02:47:35 +00:00
|
|
|
|
|
|
|
```bash
|
|
|
|
$ pip3 uninstall psycopg2 && pip3 install --no-binary :all: psycopg2
|
|
|
|
```
|