Add deployment script and configuration

.github/workflows/lint-nginx.yaml

@@ -0,0 +1,14 @@
+# GitHub Actions workflow for validating NGINX configuration files
+# https://github.com/jhinch/nginx-linter
+name: Lint NGINX config files
+on: [ push ]
+jobs:
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install nginx-linter
+        run: npm install -g nginx-linter
+      - name: Run nginx linter
+        run: nginx-linter --include config/nginx/* --no-follow-includes

.github/workflows/lint-shell-scripts.yaml

@@ -0,0 +1,14 @@
+# Lint shell scripts
+# https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
+# https://github.com/marketplace/actions/shell-linter
+name: Lint shell scripts
+on: push
+jobs:
+  lint_shell:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: azohra/shell-linter@v0.6.0
+        with:
+          severity: 'warning'
+          exclude-paths: 'LICENSE'

.github/workflows/lint-systemd.yaml

@@ -0,0 +1,14 @@
+# GitHub Actions workflow for linting the systemd unit files
+# https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
+name: Lint systemd units
+on: [ push ]
+jobs:
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install systemdlint
+        run: pip install systemdlint==1.*
+      - name: Lint systemd units
+        run: systemdlint ./config/systemd/*

README.md

@@ -61,8 +61,9 @@ python manage.py createsuperuser
 
 6. Create a `.env` file in the project root directory and add the following environment variables:
 
-```
+```bash
 DJANGO_SECRET_KEY=your_secret_key
+DJANGO_DEBUG=True
 ```
 
 ---
@@ -81,3 +82,7 @@ The app will be available at http://127.0.0.1:8000.
 ```bash
 python manage.py loaddata data\questionnaires.json data\questionnaires.json
 ```
+
+# Deployment
+
+Please read [`docs/deployment.md`](docs/deployment.md).

SORT/settings.py

@@ -14,23 +14,30 @@
 from dotenv import load_dotenv
 import os
 
-load_dotenv()  # Load environment variables from .env file
+
+def string_to_boolean(s: str) -> bool:
+    """
+    Check if the string value is 1, yes, or true.
+    """
+    return s.casefold()[0] in {"1", "y", "t"}
+
+
+# Load environment variables from .env file
+load_dotenv(os.getenv('DJANGO_ENV_PATH'))
 
 # Build paths inside the project like this: BASE_DIR / 'subdir'.
 BASE_DIR = Path(__file__).resolve().parent.parent
 
-
 # Quick-start development settings - unsuitable for production
 # See https://docs.djangoproject.com/en/5.1/howto/deployment/checklist/
 
 # SECURITY WARNING: keep the secret key used in production secret!
 SECRET_KEY = os.getenv('DJANGO_SECRET_KEY')
 
 # SECURITY WARNING: don't run with debug turned on in production!
-DEBUG = True
-
-ALLOWED_HOSTS = []
+DEBUG = string_to_boolean(os.getenv("DJANGO_DEBUG", "False"))
 
+ALLOWED_HOSTS = os.getenv('DJANGO_ALLOWED_HOSTS', '').split()
 
 # Application definition
 
@@ -82,21 +89,19 @@
     },
 ]
 
-WSGI_APPLICATION = "SORT.wsgi.application"
-
+WSGI_APPLICATION = os.getenv("DJANGO_WSGI_APPLICATION", "SORT.wsgi.application")
 
 # Database
 # https://docs.djangoproject.com/en/5.1/ref/settings/#databases
-
 DATABASES = {
+    # Set the database settings using environment variables, or default to a local SQLite database file.
     "default": {
-        "ENGINE": "django.db.backends.sqlite3",
-        "NAME": BASE_DIR / 'db.sqlite3',
-        # "NAME": os.getenv("DB_NAME"),
-        # "USER": os.getenv("DB_USER"),
-        # "PASSWORD": os.getenv("DB_PASSWORD"),
-        # "HOST": os.getenv("DB_HOST"),
-        # "PORT": os.getenv("DB_PORT"),
+        "ENGINE": os.getenv("DJANGO_DATABASE_ENGINE", "django.db.backends.sqlite3"),
+        "NAME": os.getenv("DJANGO_DATABASE_NAME", BASE_DIR / 'db.sqlite3'),
+        "USER": os.getenv("DJANGO_DATABASE_USER"),
+        "PASSWORD": os.getenv("DJANGO_DATABASE_PASSWORD"),
+        "HOST": os.getenv("DJANGO_DATABASE_HOST"),
+        "PORT": os.getenv("DJANGO_DATABASE_PORT"),
     }
 }
 
@@ -118,7 +123,6 @@
     },
 ]
 
-
 # Internationalization
 # https://docs.djangoproject.com/en/5.1/topics/i18n/
 
@@ -130,16 +134,13 @@
 
 USE_TZ = True
 
-
 # Static files (CSS, JavaScript, Images)
 # https://docs.djangoproject.com/en/5.1/howto/static-files/
 
 STATIC_URL = "static/"
 
 STATICFILES_DIRS = [BASE_DIR / 'static']
 
-
-
 # Default primary key field type
 # https://docs.djangoproject.com/en/5.1/ref/settings/#default-auto-field
 
@@ -148,14 +149,13 @@
 LOGIN_REDIRECT_URL = "/"
 LOGOUT_REDIRECT_URL = "/"
 
-
 # FA: End session when the browser is closed
 SESSION_EXPIRE_AT_BROWSER_CLOSE = True
 
 # FA: 30 minutes before automatic log out
 SESSION_COOKIE_AGE = 1800
 
-PASSWORD_RESET_TIMEOUT = 1800 # FA: default to expire after 30 minutes
+PASSWORD_RESET_TIMEOUT = 1800  # FA: default to expire after 30 minutes
 
 # FA: for local testing emails:
 
@@ -174,5 +174,6 @@
 
 # FA: for production:
 
-#EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
+# EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
 
+STATIC_ROOT = os.getenv('DJANGO_STATIC_ROOT')

SORT/wsgi.py

@@ -13,4 +13,6 @@
 
 os.environ.setdefault("DJANGO_SETTINGS_MODULE", "SORT.settings")
 
+# Create WSGI application object
 application = get_wsgi_application()
+"https://docs.djangoproject.com/en/5.1/howto/deployment/wsgi/#the-application-object"

config/README.md

@@ -0,0 +1,3 @@
+# Server configuration
+
+This directory contains configuration files for the production web server.

config/nginx/gunicorn.conf

@@ -0,0 +1,43 @@
+# https://docs.gunicorn.org/en/stable/deploy.html#nginx-configuration
+upstream app_server {
+    # fail_timeout=0 means we always retry an upstream even if it failed
+    # to return a good HTTP response
+    # for UNIX domain socket setups
+    server unix:/run/gunicorn.sock fail_timeout=0;
+}
+
+server {
+    # https://nginx.org/en/docs/http/ngx_http_core_module.html#listen
+    listen 80 deferred;
+    client_max_body_size 4G;
+    server_name sort-web-app.shef.ac.uk www.sort-web-app.shef.ac.uk;
+    keepalive_timeout 5;
+
+    # /server-status endpoint
+    # This is used by IT Services to monitor servers using collectd
+    # https://nginx.org/en/docs/http/ngx_http_stub_status_module.html
+    # https://www.collectd.org/documentation/manpages/collectd.conf.html
+    # It's based on Apache mod_status https://httpd.apache.org/docs/2.4/mod/mod_status.html
+    location = /server-status {
+        stub_status;
+    }
+
+    # Serve static files without invoking Python WSGI
+    location /static/ {
+        # https://nginx.org/en/docs/http/ngx_http_core_module.html#root
+        root /var/www/sort;
+    }
+
+    # Proxy forward to the WSGI Python app
+    location / {
+        # Set HTTP headers for the proxied service
+        # https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Host $host;
+        # we don't want nginx trying to do something clever with
+        # redirects, we set the Host: header above already.
+        proxy_redirect off;
+        proxy_pass http://app_server;
+    }
+}

config/systemd/gunicorn.service

@@ -0,0 +1,31 @@
+# This is a systemd unit that defines the Gunicorn service.
+# https://docs.gunicorn.org/en/stable/deploy.html#systemd
+# https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html
+
+[Unit]
+Description=gunicorn service
+Requires=gunicorn.socket
+After=network.target
+
+[Service]
+# gunicorn can let systemd know when it is ready
+Type=notify
+NotifyAccess=main
+# the specific user that our service will run as
+User=gunicorn
+Group=gunicorn
+# this user can be transiently created by systemd
+DynamicUser=true
+RuntimeDirectory=gunicorn
+WorkingDirectory=/opt/sort
+ExecStart=/opt/sort/venv/bin/gunicorn SORT.wsgi
+ExecReload=/bin/kill -s HUP $MAINPID
+KillMode=mixed
+TimeoutStopSec=5
+PrivateTmp=true
+# if your app does not need administrative capabilities, let systemd know
+ProtectSystem=strict
+Delegate=yes
+
+[Install]
+WantedBy=multi-user.target

config/systemd/gunicorn.socket

@@ -0,0 +1,17 @@
+# https://docs.gunicorn.org/en/stable/deploy.html#systemd
+# https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html
+[Unit]
+Description=gunicorn socket
+
+[Socket]
+ListenStream=/run/gunicorn.sock
+# Our service won't need permissions for the socket, since it
+# inherits the file descriptor by socket activation.
+# Only the nginx daemon will need access to the socket:
+SocketUser=www-data
+SocketGroup=www-data
+# Once the user/group is correct, restrict the permissions:
+SocketMode=0660
+
+[Install]
+WantedBy=sockets.target

deploy.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+set -e
+
+# SORT deployment script for Ubuntu 22.04 LTS
+# See: How to deploy Django
+# https://docs.djangoproject.com/en/5.1/howto/deployment/wsgi/#the-application-object
+
+# Usage:
+# Clone the repository
+# git clone git@github.com:RSE-Sheffield/SORT.git
+# cd SORT
+# sudo bash -x deploy.sh
+
+# Options
+sort_dir="/opt/sort"
+venv_dir="$sort_dir/venv"
+pip="$venv_dir/bin/pip"
+python_version="python3.12"
+python="$venv_dir/bin/python"
+
+# Install British UTF-8 locale so we can use this with PostgreSQL.
+# This is important to avoid the limitations of the LATIN1 character set.
+sudo locale-gen en_GB
+sudo locale-gen en_GB.UTF-8
+sudo update-locale
+
+# Create Python virtual environment
+apt update -qq
+apt install --upgrade --yes -qq "$python_version" "$python_version-venv"
+python3 -m venv "$venv_dir"
+
+# Install the SORT Django app package
+$pip install --quiet -r requirements.txt
+cp --recursive * "$sort_dir/"
+
+# Install static files into DJANGO_STATIC_ROOT
+(cd "$sort_dir" && exec $python manage.py collectstatic --no-input)
+
+# Install Gunicorn service
+cp --verbose config/systemd/gunicorn.service /etc/systemd/system/gunicorn.service
+cp --verbose config/systemd/gunicorn.socket /etc/systemd/system/gunicorn.socket
+systemctl daemon-reload
+systemctl enable gunicorn.service
+systemctl enable gunicorn.socket
+systemctl start gunicorn.service
+systemctl reload gunicorn.service
+
+# Install web reverse proxy server
+# Install nginx
+# https://nginx.org/en/docs/install.html
+apt install --yes -qq nginx
+
+# Configure web server
+rm -f /etc/nginx/sites-enabled/default
+cp config/nginx/*.conf /etc/nginx/sites-available
+# Enable the site by creating a symbolic link
+ln --symbolic --force /etc/nginx/sites-available/gunicorn.conf /etc/nginx/sites-enabled/gunicorn.conf
+systemctl reload nginx.service
+
+# Install PostgreSQL database
+# https://ubuntu.com/server/docs/install-and-configure-postgresql
+apt install --yes -qq postgresql
+# Restart PostgreSQL to enable any new locales
+systemctl restart postgresql