Merge pull request #72 from RSE-Sheffield/feat/django-logging

Set up Django logging

Author: f-allian

SORT/settings.py

@@ -181,7 +181,7 @@ def cast_to_boolean(obj: Any) -> bool:
     "127.0.0.1",
     # ...
 ]
-AUTH_USER_MODEL = 'home.User' # FA: replace username with email as unique identifiers
+AUTH_USER_MODEL = 'home.User'  # FA: replace username with email as unique identifiers
 
 # FA: for production:
 
@@ -194,3 +194,20 @@ def cast_to_boolean(obj: Any) -> bool:
     os.getenv("DJANGO_SESSION_COOKIE_SECURE", not DEBUG)
 )
 CSRF_COOKIE_SECURE = cast_to_boolean(os.getenv("DJANGO_CSRF_COOKIE_SECURE", not DEBUG))
+
+# Logging
+# https://docs.djangoproject.com/en/5.1/topics/logging/
+LOGGING = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    # Send log messages to the standard output, which will be sent to the Gunicorn service logs
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+        },
+    },
+    "root": {
+        "handlers": ["console"],
+        "level": os.getenv("DJANGO_LOG_LEVEL", "WARNING"),
+    },
+}

docs/deployment.md

@@ -42,6 +42,7 @@ This app can be deployed to a web server using the script [`deploy.sh`](../deplo
 1. Configure the `.env` file as described below.
 2. Run the deployment script: `sudo bash -x deploy.sh`
 3. Configure the database
+4. Run database migrations
 
 We can run commands and Bash scripts as the superuser (`root`) using the [`sudo` command](https://manpages.ubuntu.com/manpages/noble/en/man8/sudo.8.html).
 
@@ -147,8 +148,6 @@ We can list users (i.e. database "roles") using [the `\du`  command](https://www
 psql sort --command "\du"
 ```
 
-
-
 ## Grant permissions
 
 We must allow this user the minimum necessary privileges to operate the web app. We authorise the user using the PostgreSQL [grant statement](https://www.postgresql.org/docs/current/sql-grant.html), which we execute in the `psql` tool.
@@ -182,11 +181,63 @@ ALTER DEFAULT PRIVILEGES FOR USER sort GRANT SELECT, INSERT, UPDATE, DELETE ON T
 
 On our PostgreSQL instance, this should create a database named `sort` with a user named `sort` that has all the necessary permissions on the `sort` schema to create, modify, and drop tables and read/write data to those tables.
 
+# Database administration
+
+To open the [`psql` terminal](https://www.postgresql.org/docs/16/app-psql.html), use the [`dbshell`](https://docs.djangoproject.com/en/5.1/ref/django-admin/#dbshell) command. We can pass a command using the [`--` option](https://docs.djangoproject.com/en/5.1/ref/django-admin/#cmdoption-dbshell-0). We need to set up the shell as follows:
+
+```bash
+sort_dir="/opt/sort"
+venv_dir="$sort_dir/venv"
+python="$venv_dir/bin/python"
+psql="$python manage.py dbshell --"
+
+cd "$sort_dir"
+```
+
+To view the available PostgreSQL commands:
+
+```bash
+sudo $psql -c "\?"
+```
+
+The `psql` command invokes the Postgres shell:
+
+```bash
+$ sudo $psql
+sort=>
+```
+
+Once you're in the `psql` shell, you can exit using the `\q` command.
+
+## Manage tables
+
+### Run schema migrations
+
+Run the migrations command using [django-admin](https://docs.djangoproject.com/en/5.1/ref/django-admin/)
+
+```bash
+sudo $python manage.py migrate
+```
+
+### List tables
+
+```bash
+sudo $psql -c "\dt"
+```
+
+### Drop tables
+
+You can delete tables using the [`DROP TABLE` syntax](https://www.postgresql.org/docs/current/sql-droptable.html).
+
+```sql
+DROP TABLE IF EXISTS table_name CASCADE;
+```
+
 # Security
 
 ## SSL Certificates
 
-See: ITS Wiki [SSL Certificates/Howto](https://itswiki.shef.ac.uk/wiki/SSL_Certificates/Howto) for the commands to generate a Certificate Signing Request (CSR) using [OpenSSL](https://docs.openssl.org/3.3/man1/openssl-req/#options) with an unencrypted private key.
+See: ITS Wiki [SSL Certificates/Howto](https://itswiki.shef.ac.uk/wiki/SSL_Certificates/Howto) for the commands to generate a Certificate Signing Request (CSR) using [OpenSSL](https://docs.openssl.org/3.3/man1/openssl-req/#options) with an unencrypted private key.
 
 We can install the private key
 
@@ -218,27 +269,29 @@ To use the [Django management tool](https://docs.djangoproject.com/en/5.1/ref/dj
 sort_dir="/opt/sort"
 venv_dir="$sort_dir/venv"
 python="$venv_dir/bin/python"
+django_admin="$python $sort_dir/manage.py"
+
 cd "$sort_dir"
 # Check the Django management tool works
-$python "$sort_dir"/manage.py version
+sudo $django_admin version
 ```
 
 View available commands
 
 ```bash
-$python "$sort_dir"/manage.py help
+sudo $django_admin help
 ```
 
 Migrate the database
 
 ```bash
-sudo $python manage.py migrate
+sudo $django_admin migrate
 ```
 
 Create a super-user
 
 ```bash
-sudo $python manage.py createsuperuser
+sudo $django_admin createsuperuser
 ```
 
 Load data