225 lines
6.2 KiB
Markdown
225 lines
6.2 KiB
Markdown
[](http://translate.ojuso.org/engage/platform/?utm_source=widget)
|
|
[](https://gitlab.com/autonomic-cooperative/ojuso-map/commits/master)
|
|
[](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
|
|
```
|