Local Development Setup

Relevant source files

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

• README.md
• CONTRIBUTING.md
• roomfinder/settings.py
• generate_sample_data.py
• finder/models.py
• finder/views.py
• manage.py
• finder/templates/finder/search.html
• finder/templates/finder/upload_excel.html

This document provides a comprehensive guide for setting up the Campuspal Room Finder project for local development. The project is a Django-based web application designed to help users find available rooms on a campus. The setup process involves cloning the repository, installing dependencies, configuring the database, populating it with sample data, and running the local development server.

Following these steps will result in a fully functional local instance of the application, ready for development and testing. The setup relies on standard Python and Django tooling, with specific scripts provided for data generation and loading.

1. Prerequisites and Initial Setup

Before starting, ensure you have a compatible version of Python installed. The project uses a virtual environment to manage dependencies.

1.1. Cloning the Repository

First, create a local copy of the project by forking the repository on GitHub and then cloning your fork.

# Clone your forked repository
git clone https://github.com/YOUR_USERNAME/roomfinder.git
cd roomfinder

Sources: CONTRIBUTING.md:8-10

1.2. Environment and Dependencies

The project's dependencies are managed via pip and a requirements.txt file. It's standard practice to use a virtual environment.

1. Activate Virtual Environment:

   # Example for Windows
   my-venv\Scripts\activate
   

   Sources: README.md:270-272
2. Install Dependencies:

   pip install -r requirements.txt
   

   The required packages include Django, pandas, openpyxl, python-decouple, and dj-database-url.
   Sources: README.md:273-276, roomfinder/settings.py:8-10

2. Database Configuration

The application uses a relational database to store room and schedule information. The configuration is managed through environment variables for flexibility.

2.1. Database Settings

The database connection is configured in roomfinder/settings.py using dj_database_url. This allows the application to connect to different database backends (like PostgreSQL or SQLite) by setting a DATABASE_URL environment variable. If DATABASE_URL is not set, the project defaults to using db.sqlite3.

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

Sources: roomfinder/settings.py:85-88, README.md:43-44

2.2. Database Schema

The core data models are Room and ClassSchedule. A Room can have multiple ClassSchedule entries associated with it.

The following diagram illustrates the database schema.

This diagram shows that the Room table has a one-to-many relationship with the ClassSchedule table.
Sources: finder/models.py

2.3. Applying Migrations

Once the database is configured, apply the schema migrations to create the necessary tables.

python manage.py makemigrations finder
python manage.py migrate

Sources: README.md:277-280

3. Data Population

To use the application, the database must be populated with room and timetable data. The project includes a script to generate realistic sample data and management commands to load it.

The overall data loading flow is as follows:

This flowchart shows the two-step process of generating Excel files and then using Django management commands to load their contents into the database.
Sources: README.md:281-288, generate_sample_data.py

3.1. Generate Sample Data

Run the generate_sample_data.py script to create rooms.xlsx and timetable.xlsx inside a sample_data directory. This script generates a configurable number of rooms and class schedules with randomized details.

python generate_sample_data.py

Sources: README.md:281-284, generate_sample_data.py

3.2. Load Data into Database

Use the custom Django management commands to load the data from the generated Excel files. It's recommended to clear any existing data first to avoid duplicates.

# 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:285-288

The upload_excel view also provides a web interface at /upload/ for staff members to upload these files directly.
Sources: finder/views.py:118-123, finder/templates/finder/upload_excel.html:43-62

4. Running the Application

With the setup and data loading complete, you can run the local development server.

4.1. Start the Server

The manage.py script is the entry point for running the Django development server.

python manage.py runserver

Sources: README.md:289-291, CONTRIBUTING.md:24-25

4.2. Accessing the Application

Once the server is running, the application will be accessible at http://127.0.0.1:8000/. The root URL redirects to the main search page.

Sources: README.md:292-293, finder/views.py:252-253

The main user interface for searching is rendered by search.html.

This sequence shows how a user accessing the root URL is redirected to the search page.
Sources: finder/views.py:252-253, finder/templates/finder/search.html

5. Development and Testing

5.1. Contributing Guidelines

When making changes, follow the contribution guidelines outlined in CONTRIBUTING.md. This includes:

• Creating a new branch for your feature (git checkout -b feature/your-feature).
• Following PEP 8 style conventions.
• Adding tests for new features.

Sources: CONTRIBUTING.md:12-15, CONTRIBUTING.md:34-35

5.2. Running Tests

To ensure code quality and prevent regressions, run the test suite.

python manage.py test

Note: The finder/tests.py file is currently a placeholder and needs to be populated with actual tests.

Sources: CONTRIBUTING.md:23-24, finder/tests.py:2-3

6. Summary of Setup Commands

This table provides a quick reference for all the commands needed to set up the local development environment from scratch.

Command	Description	Source File(s)
git clone ...	Clones the repository to your local machine.	CONTRIBUTING.md:8-10
pip install -r requirements.txt	Installs all required Python packages.	README.md:273-276
python manage.py migrate	Applies database schema migrations.	README.md:277-280
python generate_sample_data.py	Creates rooms.xlsx and timetable.xlsx with sample data.	README.md:281-284
python manage.py load_rooms_excel	Loads room data from rooms.xlsx into the database.	README.md:287
python manage.py load_timetable	Loads schedule data from timetable.xlsx into the database.	README.md:288
python manage.py runserver	Starts the Django development server.	README.md:289-291
python manage.py test	Runs the project's automated tests.	CONTRIBUTING.md:23-24

This structured setup process ensures that any developer can get a consistent and functional version of the Room Finder application running on their local machine, facilitating easier contributions and testing.