Set up dependency management and package/app structure

README.md

@@ -27,75 +27,124 @@ A complete list of existing parameters is provided in the file `optimap/.env.exa
 
 ## Run with Docker
 
+The project is containerized using Docker, with services defined in `docker-compose.yml`. To start all services, run:
+
 ```bash
 docker-compose up
+```
+
+### Initial Setup
+
+After starting the containers, apply database migrations:
 
+```bash
 # run migrations, in the directory where docker-compose is to resolve the name "web"
 docker-compose run web python manage.py makemigrations
 docker-compose run web python manage.py migrate
 ```
 
-Now open a browser at <http://localhost:8000/>.
+Now open a browser at <http://localhost:8001/>.
+
+#### Services Overview
+
+- db: Runs a PostgreSQL database with PostGIS extensions. Data is persisted in a Docker volume named db_data.
+- app: Python-based app serving HTTP requests.
+- web: Our primary Django web application.
+- webserver: An Nginx server for serving static files and test files.
+
+#### Ports
+
+- 5434: Database (PostgreSQL/PostGIS)
+- 8002: App (Python HTTP server)
+- 8001: Web application (Django server)
+- 8080: Webserver (Nginx)
 
 ## Development
 
-### Test data
+### Test Data
+
+The folder `/fixtures` contains some test data, which can be used to populate the database during development. These data are provided either as SQL commands for insertion into the database or as database dumps that can be loaded using [`django-admin`](https://docs.djangoproject.com/en/dev/ref/django-admin/).
+
+### Managing Test Data
 
-The folder `/fixtures` contains some test data, either as an SQL command to insert into the database, or as a database dump that was created and can be loaded with [`django-admin`](https://docs.djangoproject.com/en/dev/ref/django-admin/).
-[`jq`](https://stedolan.github.io/jq/) is used for pretty-printing of the output.
+#### Creating Test Data Dumps
+
+To create a data dump after generating or harvesting test data, use the following command:
 
 ```bash
-# create dump after creating/harvesting test data:
 python manage.py dumpdata --exclude=auth --exclude=contenttypes | jq > fixtures/test_data.json
+```
+
+#### Loading Test Data
 
-# load:
+To load the test data into your database, run:
+
+```bash
 python manage.py loaddata fixtures/test_data.json
 ```
 
-If you want to create more testdata manually, copy and paste the existing records or add more records in the admin backend (preferred).
-A useful tool for creating sensible geometries is <https://wktmap.com/>.
+#### Adding New Test Data
+
+If additional test data is required, you can:
+
+- Copy and paste existing records.
+- Add new records via the Django admin interface (preferred method).
+- Manually modify the test data JSON file.
 
-### Run locally
+Tools for Geometries
+For creating or editing geometries, consider using the tool [WKTMap](https://wktmap.com/), which provides an easy way to generate Well-Known Text (WKT) representations of spatial data.
 
-1. Create a `.env` file based on `.env.example` in the same directory where `settings.py` resides and fill in the configuration settings as needed.
-2. Run the commands below, which use the built-in Python [`venv`](https://docs.python.org/3/library/venv.html), see [this tutorial](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments) for details
+### Run Locally
+
+1. Create a `.env` file based on `.env.example` in the same directory where `settings.py` resides, and fill in the configuration settings as needed.
+2. Run the commands below to set up and run the project locally. This setup uses the built-in Python [`venv`](https://docs.python.org/3/library/venv.html). Refer to [this tutorial](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments) for more details.
 
 ```bash
-# once only: create virtual environment
-# python -m venv .venv
+# Create a virtual environment (once only)
+python -m venv .venv
+
+# Activate the virtual environment
 source .venv/bin/activate
+
+# Confirm Python path
 which python
 
+# Install required dependencies
 pip install -r requirements.txt
 
-# create local DB container (once)
-# docker run --name optimapDB -p 5432:5432 -e POSTGRES_USER=optimap -e POSTGRES_PASSWORD=optimap -e POSTGRES_DB=optimap -d postgis/postgis:14-3.3
+# Create a local database container (once only)
+docker run --name optimapDB -p 5432:5432 -e POSTGRES_USER=optimap -e POSTGRES_PASSWORD=optimap -e POSTGRES_DB=optimap -d postgis/postgis:15-3.4
 
-# start DB
+# Start the database container
 docker start optimapDB
 
-# run migrations
+# Apply database migrations
 python manage.py makemigrations
 python manage.py migrate
 
-# create cache table
+# Create a cache table
 python manage.py createcachetable
 
-# collect static files
+# Collect static files
 python manage.py collectstatic --noinput
 
-# start app
+# Start the Django development server
 python manage.py runserver
 
-# start app with configuration for development
+# Start the app with specific configurations for development
 OPTIMAP_CACHE=dummy OPTIMAP_DEBUG=True python manage.py runserver
 ```
 
 Now open a browser at <http://127.0.0.1:8000/>.
 
-See instructions below for creating a superuser and above for loading test data.
+#### Additional Setup
 
-When you are done, deactivate the virtual environment and stop the DB with:
+- Creating a Superuser: Refer to the instructions below to create a superuser for accessing the admin interface.
+- Loading Test Data: Refer to the instructions above to load test data into the database.
+
+#### Shutting Down
+
+When finished, deactivate the virtual environment and stop the database container:
 
 ```bash
 deactivate
@@ -119,6 +168,8 @@ OPTIMAP_DEBUG=True
 
 Select the Python interpreter created above (`optimap` environment), see instructions at <https://code.visualstudio.com/docs/python/tutorial-django> and <https://code.visualstudio.com/docs/python/environments>.
 
+**Note:** The `docker-compose.yml` file is intended for **development**, not deployment.
+
 Configuration for debugging with VS Code:
 
 ```json
@@ -139,6 +190,22 @@ Configuration for debugging with VS Code:
       "justMyCode": true
     }
   ]
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Python: Django Run",
+      "type": "python",
+      "request": "launch",
+      "program": "${workspaceFolder}/manage.py",
+      "args": ["runserver"],
+      "env": {
+        "OPTIMAP_DEBUG": "True",
+        "OPTIMAP_CACHE": "dummy"
+      },
+      "django": true,
+      "justMyCode": true
+    }
+  ]
 }
 ```
 
@@ -157,20 +224,27 @@ OPTIMAP_EMAIL_HOST=localhost
 OPTIMAP_EMAIL_PORT=5587
 ```
 
-### Create superusers/admin
+### Create Superusers/Admin
 
-Superusers/admin can be created using the createsuperuser command:
+Superusers or administrators can be created using the `createsuperuser` command. This user will have access to the Django admin interface.
 
 ```bash
 python manage.py createsuperuser --username=optimap [email protected]
 ```
 
-You will be prompted for a password.
-After you enter one, the user will be created immediately. If you leave off the --username or --email options, it will prompt you for those values.
+You will be prompted for a password. After entering one, the superuser will be created immediately. If you omit the --username or --email options, the command will prompt you for those values interactively.
+
+Access the admin interface at http://127.0.0.1:8000/admin/.
+
+#### Running in a Dockerized App
 
-You can acess the admin page at <http://127.0.0.1:8000/admin/>.
+To create a superuser within the containerized application, use the following command:
 
-You can also run the command in a containerised app with `docker-compose run web python manage.py ...`.
+```bash
+docker-compose run web python manage.py createsuperuser
+```
+
+This will run the same process as above but within the Docker environment. Ensure the container is running and accessible before executing this command
 
 ## Block Emails/Domains
 
@@ -232,6 +306,17 @@ A configuration to debug the test code and also print deprecation warnings:
   },
   "django": true,
   "justMyCode": true
+  "name": "Python: Django Test",
+  "type": "python",
+  "request": "launch",
+  "pythonArgs": ["-Wa"],
+  "program": "${workspaceFolder}/manage.py",
+  "args": ["test", "tests"],
+  "env": {
+    "OPTIMAP_DEBUG": "True"
+  },
+  "django": true,
+  "justMyCode": true
 }
 ```
 
@@ -241,7 +326,7 @@ See also documentation at <https://code.visualstudio.com/docs/python/tutorial-dj
 
 ### Issues during development
 
-* If you get a message during login that there is an issue with the CSRF token, e.g. `WARNING:django.security.csrf:Forbidden (CSRF token from POST incorrect.): /loginres/` in the log and also i nthe UI, then switch to using `localhost:8000` as the domain, not the localhost IP used in the examples in this README file.
+- If you get a message during login that there is an issue with the CSRF token, e.g. `WARNING:django.security.csrf:Forbidden (CSRF token from POST incorrect.): /loginres/` in the log and also i nthe UI, then switch to using `localhost:8000` as the domain, not the localhost IP used in the examples in this README file.
 
 ## Deploy