Deployment Guide

Relevant source files

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

• README.md
• requirements.txt
• roomfinder/settings.py
• generate_sample_data.py
• finder/views.py
• finder/models.py
• roomfinder/wsgi.py

This guide provides comprehensive instructions for setting up and deploying the Campuspal Room Finder application. The project is a Django-based web application designed to help users find available rooms on a campus. A successful deployment requires setting up a Python environment, installing dependencies, configuring the application via environment variables, and populating the database with initial room and schedule data.

The application is designed to be run with a WSGI server like Gunicorn in a production environment. It relies on a PostgreSQL database, configured through a DATABASE_URL, and uses external Excel files for initial data population. This guide covers the full process from environment setup to running the application server.

Sources: README.md:1-5, 93-120, roomfinder/settings.py:1-15, requirements.txt

1. System Requirements & Dependencies

The application is built on Python and the Django framework. All required Python packages are listed in requirements.txt.

Key Dependencies

The following table lists the core dependencies required to run the application.

Package	Version	Description
Django	5.2	The web framework used for the application.
gunicorn	23.0.0	A WSGI HTTP server for running the application in production.
dj-database-url	2.3.0	Utility to configure the Django database using a URL.
python-decouple	3.8	Separates settings from source code, used for environment variables.
psycopg2-binary	2.9.10	PostgreSQL adapter for Python.
pandas	2.2.3	Used for reading and processing data from Excel files.
openpyxl	3.1.5	A Python library to read/write Excel 2010 xlsx/xlsm files.

Sources: requirements.txt

2. Configuration

Application settings are managed via environment variables, which are loaded in roomfinder/settings.py using the python-decouple library. This allows for secure and flexible configuration without modifying the source code.

Environment Variables

The following variables must be set in the deployment environment (e.g., in a .env file).

Variable	Description	Example
SECRET_KEY	A secret key for a particular Django installation. This is used to provide cryptographic signing.	'your-super-secret-key'
DEBUG	A boolean that turns on/off debug mode. Should be False in production.	False
DATABASE_URL	The connection string for the database.	'postgres://user:password@host:port/dbname'

The configuration loading mechanism is defined in roomfinder/settings.py.

# roomfinder/settings.py:22-25
# SECURITY WARNING: keep the secret key used in production secret!
SECRET_KEY = config('SECRET_KEY')

# SECURITY WARNING: don't run with debug turned on in production!
DEBUG = config('DEBUG', default=False, cast=bool)

# roomfinder/settings.py:88-90
DATABASES = {
    'default': dj_database_url.config(default=config('DATABASE_URL'))
}

Sources: roomfinder/settings.py:11, 22-25, 88-90

3. Deployment & Setup Process

The following diagram illustrates the end-to-end process for deploying the application.

This diagram shows the four main stages of deployment: environment setup, configuration, database population, and running the server.
Sources: README.md:93-120

Step-by-Step Instructions

1. Clone the Repository and Set Up Environment:
   Clone the project and create/activate a Python virtual environment.

2. Install Dependencies:
   Install all required packages from requirements.txt.

   pip install -r requirements.txt
   

   Sources: README.md:101-104

3. Configure Environment:
   Create a .env file in the project root and add the required environment variables (SECRET_KEY, DEBUG, DATABASE_URL).

4. Apply Database Migrations:
   Run the Django migrate command to apply the database schema. The schema includes the Room and ClassSchedule models.

   python manage.py migrate
   

   Sources: README.md:105-108, finder/models.py

5. Generate and Load Initial Data:
   The application requires an initial dataset of rooms and schedules, which is loaded from Excel files.

   Data Loading Flow

This sequence shows that the user first runs a script to generate data files, then uses management commands to load that data into the database.
Sources: [README.md:109-117](https://github.com/Allen739/roomfinder/blob/HEAD/README.md#L109-L117), [generate_sample_data.py](https://github.com/Allen739/roomfinder/blob/HEAD/generate_sample_data.py), [finder/views.py:126-237](https://github.com/Allen739/roomfinder/blob/HEAD/finder/views.py#L126-L237)

*   **Generate Sample Data Files**: Run the provided script to create `rooms.xlsx` and `timetable.xlsx` in the `sample_data/` directory.
    ```bash
    python generate_sample_data.py
    ```
    This script generates realistic data for rooms, including capacity and amenities, and a timetable with courses and schedules.
    Sources: [README.md:109-112](https://github.com/Allen739/roomfinder/blob/HEAD/README.md#L109-L112), [generate_sample_data.py:34-71](https://github.com/Allen739/roomfinder/blob/HEAD/generate_sample_data.py#L34-L71)

*   **Load Data into Database**: Before loading, clear any existing data. Then, run the custom management commands to populate the database from the generated Excel files.
    ```bash
    # Clear existing data
    python manage.py shell -c "from finder.models import Room, ClassSchedule; Room.objects.all().delete(); ClassSchedule.objects.all().delete()"

    # Load new data
    python manage.py load_rooms_excel
    python manage.py load_timetable
    ```
    Sources: [README.md:113-117](https://github.com/Allen739/roomfinder/blob/HEAD/README.md#L113-L117)

4. Running the Server

Development

For development purposes, use the built-in Django development server.

python manage.py runserver

The application will be accessible at http://127.0.0.1:8000/.
Sources: README.md:118-120

Production

In a production environment, use a WSGI server like Gunicorn. The roomfinder/wsgi.py file provides the application entry point for the WSGI server.

# roomfinder/wsgi.py
"""
WSGI config for roomfinder project.

It exposes the WSGI callable as a module-level variable named ``application``.
"""

import os

from django.core.wsgi import get_wsgi_application

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "roomfinder.settings")

application = get_wsgi_application()

To run the application with Gunicorn, point it to the wsgi module:

gunicorn roomfinder.wsgi:application

This command starts Gunicorn, which serves the Django application. For a robust setup, configure Gunicorn with multiple workers and run it behind a reverse proxy like Nginx.
Sources: roomfinder/wsgi.py, requirements.txt

5. Summary

Deploying the Room Finder application involves a standard Django deployment workflow with an added critical step for data population. Key takeaways are the reliance on environment variables for configuration, the use of a PostgreSQL database, and the two-step process for generating and loading initial room and schedule data. Following the steps outlined in this guide will ensure a successful deployment for both development and production environments.