Running the Application

Relevant source files

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

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

This document provides a comprehensive guide to setting up, configuring, populating, and running the Campuspal Room Finder application. It covers the necessary dependencies, database setup, data loading procedures, and the steps required to launch the development server. The process involves installing Python packages, applying database migrations, generating and loading sample data, and finally, running the Django server.

The application is a standard Django project that uses a WSGI interface for deployment. It relies on a database (configurable via environment variables) to store room and schedule information, which is initially populated from Excel files. The frontend is served as static assets managed by Django.

1. Prerequisites and Installation

Before running the application, the development environment must be set up with the required Python dependencies. The project uses a requirements.txt file to manage these packages.

The setup process involves creating a virtual environment, activating it, and installing the packages listed in requirements.txt.

Sources: README.md:213-221

Dependencies

While the requirements.txt file is not provided, the README.md implies the following key dependencies are required for the application to function.

Package	Description	Source
Django	The core web framework.	README.md:8
pandas	Used for reading and processing .xlsx files.	README.md:221, finder/views.py:6
openpyxl	A dependency for pandas to handle Excel files.	README.md:221
decouple	Used for separating settings from source code.	roomfinder/settings.py:8
dj_database_url	Utility to configure the database from a URL.	roomfinder/settings.py:10

Sources: README.md:8, 221, roomfinder/settings.py:8, 10, finder/views.py:6

2. Configuration

The application's configuration is managed in roomfinder/settings.py and relies on environment variables for sensitive information, facilitated by the decouple library.

Environment Variables

The following environment variables must be set for the application to run correctly.

Variable	Description	Example Value	Source
SECRET_KEY	A secret key for a particular Django installation, used for cryptographic signing.	'your-django-secret-key'	roomfinder/settings.py:21
DEBUG	A boolean that turns on/off debug mode. Should be False in production.	True	roomfinder/settings.py:24
DATABASE_URL	A URL string used to configure the database connection. Defaults to SQLite if not set.	postgres://user:pass@host:port/dbname	roomfinder/settings.py:89

Sources: roomfinder/settings.py:21, 24, 89

Database Configuration

The database is configured using dj_database_url, which parses the DATABASE_URL environment variable. This allows for flexible database backend configuration without changing the code.

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

Sources: roomfinder/settings.py:88-90

3. Setup and Execution Flow

Running the application for the first time involves a sequence of steps from cloning the repository to starting the development server.

This diagram illustrates the end-to-end process for setting up and running the application.

3.1. Database Initialization

The database schema is defined by the models in finder/models.py. The Room and ClassSchedule models must be created as tables in the database. This is accomplished using Django's migration commands.

1. python manage.py makemigrations finder: Creates new migration files based on changes detected in finder/models.py.
2. python manage.py migrate: Applies the migrations, creating the database tables.

Sources: README.md:222-225, finder/models.py

The following Entity-Relationship diagram shows the database schema created by the migrations.

3.2. Data Population

After the database is initialized, it must be populated with data. The project provides a script to generate sample Excel files and Django management commands to load this data into the database.

Data Generation and Loading Flow

1. Generate Sample Data: The generate_sample_data.py script creates two Excel files (rooms.xlsx and timetable.xlsx) in the sample_data/ directory. These files contain realistic-looking data for rooms and their schedules.

   python generate_sample_data.py
   

   Sources: README.md:227-230, generate_sample_data.py

2. Clear Existing Data (Optional but Recommended): Before loading new data, it's good practice to clear any existing records from the Room and ClassSchedule tables to avoid conflicts.

   python manage.py shell -c "from finder.models import Room, ClassSchedule; Room.objects.all().delete(); ClassSchedule.objects.all().delete()"
   

   Sources: README.md:231-232

3. Load Data into Database: The README.md describes two custom management commands to parse the generated Excel files and populate the database.

   • python manage.py load_rooms_excel: Reads rooms.xlsx and populates the Room model.
   • python manage.py load_timetable: Reads timetable.xlsx and populates the ClassSchedule model.

   Sources: README.md:193-199, 233-234

3.3. Running the Development Server

Once the database is set up and populated, the Django development server can be started using the runserver command.

python manage.py runserver

The application will then be accessible at http://127.0.0.1:8000/. The root URL redirects to the main search page.

Sources: README.md:238-241, finder/views.py:255-256

4. Application Entrypoints

The application is served via a WSGI interface, which is the standard for deploying Python web applications.

• roomfinder/wsgi.py: This file exposes the WSGI callable. It sets the DJANGO_SETTINGS_MODULE environment variable to point to the project's settings file and gets the WSGI application object.
• roomfinder/settings.py: Defines the ROOT_URLCONF as "roomfinder.urls", which is the entry point for all URL routing within the Django application.
• INSTALLED_APPS: The "finder.apps.FinderConfig" app is registered, making its models, views, and URLs available to the project.

Sources: roomfinder/wsgi.py:12-14, roomfinder/settings.py:40, 61