Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• pbp-deploy.sh
• becathlon/wsgi.py
• requirements.txt
• becathlon/settings.py
• collect_static.py
• README.md
• reset_production_db.py

This guide provides a technical overview of the deployment process for the Becathlon Django application. The project is designed for deployment on a Platform-as-a-Service (PaaS) environment, specifically the PWS (Platform Web Service) at the University of Indonesia. The deployment is automated through a shell script that handles dependency installation, static file collection, and database migrations.

The configuration is managed through environment variables, allowing for a flexible setup that distinguishes between local development and production environments. Key components like the database, static file serving, and security settings are dynamically configured based on these variables.

1. Prerequisites

The application relies on a set of Python packages defined in requirements.txt. The production environment must have these dependencies installed.

Key Dependencies

Package	Version	Purpose
Django	==5.2.5	The core web framework.
psycopg2-binary	==2.9.9	PostgreSQL adapter for production database connectivity.
whitenoise	==6.7.0	Serves static files directly from the web server in production.
gunicorn	==22.0.0	WSGI HTTP Server for running the Django application in production.

Sources: requirements.txt

2. Environment Configuration

The application's behavior is controlled by environment variables, which are read in becathlon/settings.py. This allows for secure and flexible deployment without hardcoding sensitive information.

Configuration Flow

The following diagram illustrates how environment variables are used to configure the Django application at runtime.

Sources: becathlon/settings.py:28-51, becathlon/settings.py:113-140, becathlon/settings.py:183-184

Environment Variables

The following table lists the primary environment variables used to configure the application for a production environment.

Variable	Description	Default/Fallback
SECRET_KEY	Django's secret key for cryptographic signing.	A default insecure key (for development only).
DEBUG	Toggles Django's debug mode. Should be 'False' in production.	'True'
ALLOWED_HOSTS	A comma-separated list of allowed hostnames.	'localhost,127.0.0.1,testserver'
DB_NAME	The name of the PostgreSQL database.	None (triggers SQLite fallback)
DB_USER	The username for the PostgreSQL database.	None
DB_PASSWORD	The password for the PostgreSQL database.	None
DB_HOST	The host address of the PostgreSQL database.	None
DB_PORT	The port for the PostgreSQL database.	'5432'
SCHEMA	The PostgreSQL schema to use.	None
STATIC_ROOT	The absolute path to the directory where collectstatic will collect static files.	BASE_DIR / 'staticfiles'
MEDIA_ROOT	The absolute path to the directory for user-uploaded media.	BASE_DIR / 'media'

Sources: becathlon/settings.py:28-33, becathlon/settings.py:113-121, becathlon/settings.py:183-188

Production Security Settings

When DEBUG is False, several security enhancements are enabled:

• SESSION_COOKIE_SECURE = True: Ensures session cookies are only sent over HTTPS.
• CSRF_COOKIE_SECURE = True: Ensures CSRF cookies are only sent over HTTPS.
• CSRF_TRUSTED_ORIGINS: A list of trusted origins for CSRF protection, including the PWS deployment URL.

Sources: becathlon/settings.py:40-51

3. Deployment Process

The deployment to the PWS environment is automated by the pbp-deploy.sh script. This script is executed automatically by the PaaS during the deployment lifecycle.

Deployment Script (pbp-deploy.sh)

#!/bin/bash
# Deployment script for PWS
# This script runs automatically during deployment

set -e  # Exit on error

echo "=== PWS Deployment Script ==="
echo "Starting deployment for Becathlon..."

# Create necessary directories
echo "Creating directories..."
mkdir -p /tmp/staticfiles
mkdir -p /tmp/media

# Collect static files
echo "Collecting static files..."
python manage.py collectstatic --noinput --clear

# Run migrations
echo "Running database migrations..."
python manage.py migrate --noinput

echo "=== Deployment Complete ==="

Sources: pbp-deploy.sh

Deployment Flow

The script executes a sequence of commands to prepare the application for serving.

Sources: pbp-deploy.sh:11-21

4. Static Files Handling

In production, static files (CSS, JavaScript, images) are served by WhiteNoise. The configuration in settings.py and the deployment script work together to manage this process.

Configuration

• STATIC_URL: The URL to use when referring to static files (e.g., /static/).
• STATIC_ROOT: The directory where all static files from different apps are collected. The deployment script creates /tmp/staticfiles for this purpose, but the settings.py default is BASE_DIR / 'staticfiles'. The environment variable STATIC_ROOT will override this.
• STORAGES: The staticfiles storage is set to whitenoise.storage.CompressedStaticFilesStorage, which compresses files and handles caching headers.
• MIDDLEWARE: whitenoise.middleware.WhiteNoiseMiddleware is included to serve the files.

Sources: becathlon/settings.py:84-85, becathlon/settings.py:183-184, becathlon/settings.py:192-204

Collection Process

The collectstatic command, executed by pbp-deploy.sh, triggers the following process:

Sources: pbp-deploy.sh:17, collect_static.py:19, becathlon/settings.py:196-198

5. Database Management

Production Database

The application is configured to use PostgreSQL in production. The connection details are provided entirely through environment variables (DB_NAME, DB_USER, etc.). If these variables are not set, the application falls back to a local db.sqlite3 file, which is suitable for development.

Sources: becathlon/settings.py:113-140

Database Reset

For fresh deployments or to resolve migration issues, the reset_production_db.py script is provided. This is a destructive operation and should be used with caution.

Functionality:

1. Prompts the user for confirmation by typing YES DELETE EVERYTHING.
2. Connects to the database and drops all tables in the current schema.
3. Runs python manage.py migrate to create a fresh database schema.
4. Executes seed_product_types.py to populate initial data.

Sources: reset_production_db.py

6. Application Server (WSGI)

The entry point for the production web server (like Gunicorn) is the WSGI application object defined in becathlon/wsgi.py. This file sets the DJANGO_SETTINGS_MODULE environment variable and exposes the Django application instance.

# becathlon/wsgi.py
import os
from django.core.wsgi import get_wsgi_application

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'becathlon.settings')

application = get_wsgi_application()

Sources: becathlon/wsgi.py

Summary

The deployment architecture of Becathlon is streamlined for PaaS environments. It leverages a shell script for automation, environment variables for flexible configuration, and WhiteNoise for efficient static file serving. The process ensures that the application is correctly configured with a production-ready database, migrated schema, and collected static assets before it starts serving traffic. The provided utility scripts for static collection and database resets further aid in managing the production environment.