Deployment Guide

Relevant source files

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

• locallibrary/settings.py
• README.md
• requirements.txt
• runtime.txt
• locallibrary/wsgi.py

This document provides a technical guide for deploying the Django Local Library application. It covers environment setup, configuration, dependencies, and the necessary steps to run the application in both development and production-like environments. The information is derived exclusively from the project's source files.

The application is a web-based catalog for a small library, allowing users to browse books and authors. The deployment process relies on standard Django practices, with specific configurations for handling environment variables, static files, and database connections, making it suitable for platforms like Railway or PythonAnywhere.

1. Prerequisites and Dependencies

Before deploying the application, the target environment must meet specific runtime and package requirements.

1.1. Python Runtime

The application specifies a required Python runtime version.

File	Runtime
runtime.txt	python-3.10.13

Sources: runtime.txt

1.2. Python Packages

The application's dependencies are listed in requirements.txt. These packages must be installed using pip.

Package	Description
asgiref	ASGI compatibility library for Django.
dj-database-url	Utility to configure the Django DATABASES setting from a DATABASE_URL environment variable.
Django	The core web framework.
django-bootstrap-v5	Integration for Bootstrap 5 with Django.
gunicorn	A Python WSGI HTTP Server for UNIX.
psycopg2-binary	PostgreSQL database adapter for Python.
python-dotenv	Reads key-value pairs from a .env file and sets them as environment variables.
sqlparse	A non-validating SQL parser for Python.
tzdata	Timezone database for Python.
whitenoise	Radically simplified static file serving for Python web apps.

Sources: requirements.txt

The following diagram illustrates the process of setting up the environment dependencies.

2. Application Configuration

The primary configuration file is locallibrary/settings.py. It is designed to be flexible for both development and production by using environment variables to override default settings.

2.1. Environment Variables

The application uses python-dotenv to load environment variables from a .env file located in the project's base directory. This allows for secure management of sensitive data without hardcoding it.

Sources: locallibrary/settings.py:18-20

The diagram below shows how settings are loaded and potentially overridden by environment variables.

2.2. Key Deployment Settings

The following settings in locallibrary/settings.py are critical for a production deployment.

Setting	Description	Default / Production Value
SECRET_KEY	A secret key for a particular Django installation. Kept secret in production.	Loaded from DJANGO_SECRET_KEY env var, with a fallback for development.
DEBUG	Toggles debug mode. Must be False in production.	True by default. Set to False if DJANGO_DEBUG env var is 'False'.
ALLOWED_HOSTS	A list of strings representing the host/domain names that this Django site can serve.	['.railway.app', '.pythonanywhere.com', '127.0.0.1']
CSRF_TRUSTED_ORIGINS	A list of trusted origins for unsafe requests (e.g., POST).	['https://*.railway.app', 'https://*.pythonanywhere.com']
DATABASES	Database connection settings.	Defaults to SQLite. Overridden by DATABASE_URL env var for production (e.g., PostgreSQL).
STATIC_ROOT	The absolute path where collectstatic will collect static files.	BASE_DIR / 'staticfiles'
STATIC_URL	URL to use when referring to static files.	/static/
STORAGES	Configures storage backends, including for static files.	Uses whitenoise.storage.CompressedManifestStaticFilesStorage for efficient static file serving.

Sources: locallibrary/settings.py:26-41, 91-97, 115-135

3. Web Server Gateway Interface (WSGI)

The locallibrary/wsgi.py file serves as the entry point for a WSGI-compatible web server (like Gunicorn) to run the application. It gets the Django application object and makes it available to the server.

# locallibrary/wsgi.py
import os

from django.core.wsgi import get_wsgi_application

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

application = get_wsgi_application()

This configuration points the server to the project's settings.py file and provides the application callable that the server will use to communicate with Django.

Sources: locallibrary/wsgi.py

4. Static File Handling

For production, static files (CSS, JavaScript, images) are handled by the WhiteNoise library.

4.1. Configuration

WhiteNoise is configured via middleware and storage settings.

1. Middleware: whitenoise.middleware.WhiteNoiseMiddleware is added to the MIDDLEWARE list, ideally right after the SecurityMiddleware.
2. Storage: The staticfiles storage backend is set to whitenoise.storage.CompressedManifestStaticFilesStorage. This enables compression (Gzip, Brotli) and caching of static files.

# locallibrary/settings.py:68
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'whitenoise.middleware.WhiteNoiseMiddleware',
    # ...
]

# locallibrary/settings.py:130-135
STORAGES = {
    # ...
    "staticfiles": {
        "BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage",
    },
}

Sources: locallibrary/settings.py:68-69, 130-135

4.2. Deployment Step

Before running the server in production, the collectstatic command must be executed. This command gathers all static files from the installed apps into the directory specified by STATIC_ROOT.

python3 manage.py collectstatic

Sources: README.md:24, locallibrary/settings.py:125-126

The following sequence diagram shows how a request for a static file is handled by WhiteNoise.

5. Local Setup and Execution

The README.md file provides a quick start guide to run the application locally. This process is a prerequisite for understanding the full deployment.

The steps are as follows:

1. Install dependencies from requirements.txt.
2. Run makemigrations to create new migrations based on model changes.
3. Run migrate to apply database migrations.
4. Run collectstatic to gather static files.
5. (Optional) Run test to execute the test suite.
6. (Optional) Run createsuperuser to create an admin user.
7. Run runserver to start the development server.

This workflow is summarized in the flowchart below.