Update docs, add example .env file

virtualenvwrapper guide, merge / tidy up database installation
instructions

README.md

@@ -8,6 +8,9 @@ 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
@@ -39,7 +42,51 @@ $ sudo postgresql-setup --initdb --unit 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:
 
@@ -48,75 +95,67 @@ $ python3 -m venv .venv
 $ source .venv/bin/activate
 ```
 
-(to leave the virtual environment, the command is simply `deactivate`)
-
-## Configure the Environment
-
-```bash
-$ export DEBUG=1
-$ export DJANGO_SETTINGS_MODULE=ojusomap.settings
-```
-
-## Install the Python Dependencies
+Then install python dependencies:
 
 ```bash
 $ pip3 install --upgrade pip setuptools
 $ 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
-$ 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
 
-### 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
-$ 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)
-to change the Postgres authentication options (NB on Fedora / Centos,
-`pg_hba.conf` is located in `/var/lib/pgsql/data`), then run:
+Now, either set a password on the `postgres` user:
 
-```bash
-$ echo "ALTER USER postgres WITH PASSWORD 'postgres';" | psql -U postgres
+```sql
+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
-
-```bash
-$ sudo su postgres
-```
-Then get an interactive postgres shell
-
-```
-$ psql
+```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;  
 ```
 
-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.
 
-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
 
@@ -130,21 +169,42 @@ $ python manage.py migrate
 $ python manage.py runserver
 ```
 
+(Use `Ctrl+C` to stop the server)
+
 # 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
 $ cd ojuso-map
 $ source .venv/bin/activate
-$ export DEBUG=1
-$ export DJANGO_SETTINGS_MODULE=ojusomap.settings
 $ 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
+```

example.env

@@ -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...