Update dev commands with docs

2021-10-15 15:20:14 +13:00 · 2021-10-15 15:20:14 +13:00 · 1cb7403f6f
commit 1cb7403f6f
parent 299e609c25
5 changed files with 167 additions and 23 deletions
--- a/README.md
+++ b/README.md
@ -1,9 +1,7 @@
 # RightTree

 Right Plant Right Place Right Time implementation using React and Django.
-
-## Running application for development
-### Initial Setup
+## Initial Setup

 Before running the applications please ensure the following prerequisites have been met.
 #### Software
@ -15,20 +13,56 @@ $ sudo apt install git docker-compose

 To install `docker`, follow the [official installation documentation](https://docs.docker.com/get-docker/). [Instructions are also available for `docker-compose`](https://docs.docker.com/compose/install/).

-#### Initialise database
+You may also need to give the `dev` script executable permissions using the following command:
+
+```
+chmod +x ./dev
+```
+
+### Add shapefiles for database population
+
+Please unzip and add the following shapefiles to the `./backend/right_tree/api/data/resources` directory. It should include all the files required by the shapefile and use naming conventions as follows:
+
+**Ecological Districts Shapefile:**
+```
+backend/right_tree/api/data/resources/ecological_districts/
+- DOC_EcologicalDistricts_2021_08_02.cpg
+- DOC_EcologicalDistricts_2021_08_02.dbf
+- DOC_EcologicalDistricts_2021_08_02.prj
+- DOC_EcologicalDistricts_2021_08_02.sbn
+- DOC_EcologicalDistricts_2021_08_02.sbx
+- DOC_EcologicalDistricts_2021_08_02.shp
+- DOC_EcologicalDistricts_2021_08_02.shp.xml
+- DOC_EcologicalDistricts_2021_08_02.shx
+```
+
+**Ecological Districts Shapefile:**
+```
+backend/right_tree/api/data/resources/fundamental_soil_layers/
+- fundamental-soil-layers-new-zealand-soil-classification.cpg
+- fundamental-soil-layers-new-zealand-soil-classification.dbf
+- fundamental-soil-layers-new-zealand-soil-classification.prj
+- fundamental-soil-layers-new-zealand-soil-classification.shp
+- fundamental-soil-layers-new-zealand-soil-classification.shx
+- fundamental-soil-layers-new-zealand-soil-classification.xml
+```
+### Add spreadsheet data for database population
+
+The plant spreadsheet should be renamed as `plant_data.xlsx` and placed in the `./backend/right_tree/api/data/resources` directory. 
+## Running application for development
+### Initial build
+
+Builds the Django backend docker image. This may need to be re-run if any new dependencies are added.
+```
+./dev build
+```
+
+### Initialise database

 Creates `right_tree` database and installs `postgis` extensions.

 ```
-chmod +x ./database/init_database.sh
-./database/init_database.sh
-```
-
-#### Initial build
-
-Builds the Django backend docker image. This may need to be re-run if any new dependencies are added.
-```
-docker-compose build
+./dev init_database
 ```

 ### Run web application
@ -36,7 +70,7 @@ docker-compose build
 Starts up the applications including the frontend, backend and database.

 ```
-docker-compose up
+./dev start
 ```

 Once running the components can be accessed as follows:
@ -45,4 +79,31 @@ Once running the components can be accessed as follows:
 | --- | --- |
 | React Frontend | http://localhost:3000 |
 | Django Backend | http://localhost:8000 |
-| Database | postgis://localhost:5432 |
+| Database | postgis://localhost:5432 |
+
+## Available commands
+
+Other commands can be run using the following. 
+```
+./dev <command>
+```
+
+A summary of available commands are outlined below. Note that if the command requires the application to be running (`Requires Run`) please execute `./dev start` in another terminal before running that command.
+
+| Command | Description | Requires Run |
+| --- | --- | --- |
+| `create_database` | Removes the existing database and data. Then it creates the `right_tree` database within a fresh postgis database instance. | No
+| `makemigrations` | Performs the django `makemigrations` command in the backend container. | Yes 
+| `migrate` | Performs the django `migrate` command in the backend container. | Yes
+| `createsuperuser` | Performs the django `createsuperuser` command in the backend container. | Yes
+| `load_fixtures` | Performs the django `loaddata` command in the backend container. This loads all the fixtures found in the `/backend/right_tree/api/data/fixtures` directory. | Yes
+| `load_shapefiles` | Performs the custom `loadshapefiles` command in the backend container. This loads the ecological districts and soil layers shape files in `c`. | Yes
+| `create_plant_fixtures` | Performs the custom `createplantfixtures` command in the backend container. This loads the plant spreadsheet data from `/backend/right_tree/api/data/resources/plant_data.xlsx`. Requires the fixtures to be applied and shapefiles loaded. | Yes
+| `reset_plants` | Performs the custom `resetplants` command in the backend container. This removes all plant entries from the database. | Yes
+| `load_plant_fixtures` | Loads the `/backend/right_tree/api/data/fixtures/plants.json` fixture. Requires the `plants.json` file to be created (`./dev create_plant_fixtures`) and the plant table to be empty (`./dev reset_plants`). | Yes
+| `load_plants` | Creates plants fixtures and loads them into a fresh plant table in the database. Requires the fixtures to be applied and shapefiles loaded. | Yes
+| `populate_database` | Populates the `right_tree` database with base data (fixtures), provided shapefiles and plant spreadsheet data. Requires the database to be created. | No
+| `init_database` | Creates and populates the database | No
+| `reset_database` | Removes, recreates and populates the database | No
+| `build` | Builds required images | No
+| `start` | Runs all services including the frontend, backend and postgres database | No
--- a/database/init/001_init_righttree.sql
+++ b/database/init/001_init_righttree.sql
--- a/database/init_database.sh
+++ b/database/init_database.sh
@ -1,3 +0,0 @@
-docker-compose down --remove-orphans --volumes
-docker-compose up postgres | sed '/PostgreSQL init process complete; ready for start up./q'
-docker-compose down
--- a/89
+++ b/89
@ -0,0 +1,89 @@
+#!/bin/bash
+
+cmd_create_database() {
+    echo "Creating right_tree database..."
+    docker-compose down --remove-orphans --volumes
+    docker-compose -f docker-compose.yaml up postgres | sed '/PostgreSQL init process complete; ready for start up./q'
+    docker-compose down
+}
+
+cmd_makemigrations() {
+    echo "Creating database migrations..."
+    docker-compose exec django-backend python manage.py makemigrations --no-input
+}
+
+cmd_migrate() {
+    echo "Running database migrations..."
+    docker-compose exec django-backend python manage.py migrate
+}
+
+cmd_createsuperuser() {
+    echo "Loading shapefiles into the database..."
+    docker-compose exec django-backend python manage.py createsuperuser --noinput
+}
+
+cmd_load_fixtures() {
+    echo "Loading fixtures..."
+    docker-compose exec django-backend bash -c "python manage.py loaddata right_tree/api/data/fixtures/*.json"
+}
+
+cmd_load_shapefiles() {
+    echo "Loading shapefiles into the database..."
+    docker-compose exec django-backend python manage.py loadshapefiles
+}
+
+cmd_create_plant_fixtures() {
+    echo "Creates fixtures for plants using spreadsheet."
+    docker-compose exec django-backend python manage.py createplantfixtures
+}
+
+cmd_reset_plants() {
+    echo "Resetting plants..."
+    docker-compose exec django-backend python manage.py resetplants
+}
+
+cmd_load_plant_fixtures() {
+    echo "Loading plants..."
+    docker-compose exec django-backend python manage.py loaddata right_tree/api/data/fixtures/plants.json
+}
+
+cmd_load_plants() {
+    cmd_create_plant_fixtures
+    cmd_reset_plants
+    cmd_load_plant_fixtures    
+}
+
+cmd_populate_database() {
+    echo "Populating the database..."
+    docker-compose up -d django-backend postgres
+
+    cmd_makemigrations
+    cmd_migrate
+    cmd_createsuperuser
+    cmd_load_fixtures
+    cmd_load_shapefiles
+    cmd_load_plants
+
+    docker-compose down
+}
+
+cmd_init_database() {
+    cmd_create_database
+    cmd_populate_database
+}
+
+cmd_reset_database() {
+    cmd_init_database
+}
+
+cmd_build() {
+    docker-compose build
+}
+
+cmd_start() {
+    docker-compose up
+}
+
+# Run the command
+cmd="$1"
+"cmd_$cmd" "$@"
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@ -17,10 +17,7 @@ services:
      - ./backend:/app
    ports:
      - "8000:8000"
-    command: bash -c "./manage.py makemigrations; 
-                      ./manage.py migrate; 
-                      ./manage.py createsuperuser --noinput;
-                      ./manage.py runserver 0.0.0.0:8000"
+    command: bash -c "./manage.py runserver 0.0.0.0:8000"

  react-frontend:
    image: node:16-alpine3.11
@ -39,7 +36,7 @@ services:
    container_name: postgres
    volumes:
      - local-postgres-data:/var/lib/postgresql/data
-      - ./database/init:/docker-entrypoint-initdb.d
+      - ./create_database.sql:/docker-entrypoint-initdb.d/create_database.sql
    ports:
      - "5432:5432"
    environment: