autonomic-cooperative/ojuso-map
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs, add example .env file

Browse Source 
virtualenvwrapper guide, merge / tidy up database installation
instructions
This commit is contained in:
Carl van Tonder 2018-09-22 22:47:35 -04:00 committed by Naomi
parent 78b597166f
commit 02bf06e9ad
2 changed files with 116 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
README.md
View File

@ -8,6 +8,9 @@ Kickass map for the Ojuso Project
# Getting Started # Getting Started
(These instructions are for GNU/Linux. Running this application on other
platforms will probably work.. good luck!)
## Check out the code ## Check out the code
```bash ```bash
@ -39,7 +42,51 @@ $ sudo postgresql-setup --initdb --unit postgresql
$ sudo systemctl start postgresql $ sudo systemctl start postgresql
``` ```
## Bootstrap the Virtual Environment ## 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: Set up your Python virtual environment in the `.venv` folder:
@ -48,75 +95,67 @@ $ python3 -m venv .venv
$ source .venv/bin/activate $ source .venv/bin/activate
``` ```
(to leave the virtual environment, the command is simply `deactivate`) Then install python dependencies:
## Configure the Environment
```bash
$ export DEBUG=1
$ export DJANGO_SETTINGS_MODULE=ojusomap.settings
```
## Install the Python Dependencies
```bash ```bash
$ pip3 install --upgrade pip setuptools $ pip3 install --upgrade pip setuptools
$ pip3 install -r requirements-devel.txt $ pip3 install -r requirements-devel.txt
``` ```
If you run into issues with `psycopg2` you may need to run the following: ## 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 ```bash
$ pip3 uninstall psycopg2 && pip3 install --no-binary :all: psycopg2 $ 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 ## Set up database
### Method 1 You need to configure Postgres to allow password (it calls it `md5`)
authentication, and set up a user with superuser privileges on a database.
You should be able to connect to Postgres: 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 ```bash
$ psql -U postgres -h localhost $ psql -U postgres
``` ```
(enter "postgres" as the password) (you may need `sudo -u postgres psql` depending on your security configuration)
If not, follow [these instructions](https://stackoverflow.com/a/51872624/399367) Now, either set a password on the `postgres` user:
to change the Postgres authentication options (NB on Fedora / Centos,
`pg_hba.conf` is located in `/var/lib/pgsql/data`), then run:
```bash ```sql
$ echo "ALTER USER postgres WITH PASSWORD 'postgres';" | psql -U postgres postgres=# ALTER USER postgres WITH PASSWORD 'postgres';
``` ```
### Method 2 or create a new user account and database:
First you need to switch to the user called postgres - in Linux do ```sql
postgres=# CREATE DATABASE ojuso;
```bash postgres=# CREATE USER ojuso WITH PASSWORD 'ojuso';
$ sudo su postgres 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
Then get an interactive postgres shell postgres=# GRANT ALL PRIVILEGES on database ojuso to ojuso;
postgres=# ALTER USER ojuso with superuser;
```
$ psql
``` ```
Then create a database and a user, and ensure to make the user a superuser (otherwise you will run into trouble when doing the migration and it tries to enable the postgis extension).
```bash
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. Type `\q` to exist the postgres shell.
Then, in `ojuso-map/ojusomap/settings.py`, edit the `DATABASES` section to add the database name, user and password, which are all 'ojuso' unless you chose different ones in the previous step. 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 ## Run The Migrations
@ -130,21 +169,42 @@ $ python manage.py migrate
$ python manage.py runserver $ python manage.py runserver
``` ```
(Use `Ctrl+C` to stop the server)
# Resuming work # Resuming work
For each new terminal session, you will need to run: 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 ```bash
$ cd ojuso-map $ cd ojuso-map
$ source .venv/bin/activate $ source .venv/bin/activate
$ export DEBUG=1
$ export DJANGO_SETTINGS_MODULE=ojusomap.settings
$ python manage.py runserver $ python manage.py runserver
``` ```
(and `$ source .env` if you're not using `auotenv` or `direnv`)
# Running The Tests # Running The Tests
```bash ```bash
$ pip install -r requirements-test.txt $ pip install -r requirements-test.txt
$ python manage.py collectstatic
$ pytest -v $ 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
```

10
example.env Normal file
View File

@ -0,0 +1,10 @@
# edit these as appropriate, save this file to .env, and source it before
# running Django commands (see README for tips on doing that automatically)
DEBUG=1
DJANGO_SETTINGS_MODULE=ojusomap.settings
DJANGO_PORT=8008
PYTHONPATH=$PYTHONPATH:`pwd`
#DATABASE_NAME=ojuso
# etc...