Troubleshooting Guide

Relevant source files

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

• becathlon/settings.py
• pbp-deploy.sh
• reset_production_db.py
• apps/main/templates/main/home.html
• README.md
• IMPLEMENTATION.md
• becathlon/urls.py

This guide provides solutions and diagnostic steps for common issues encountered during the development, deployment, and maintenance of the Becathlon application. It covers problems related to environment configuration, database management, deployment processes, and frontend functionality. The goal is to equip developers with the necessary information to quickly identify and resolve problems by referencing the project's specific implementation details.

Configuration and Environment

Proper environment configuration is critical for the application to run correctly. Most configuration is managed through environment variables, which dictate settings for debugging, database connections, and security.

Sources: becathlon/settings.py

Key Environment Variables

The application's behavior, particularly the distinction between development and production environments, is controlled by several environment variables defined in becathlon/settings.py.

Variable	Description	Default Value	Source
SECRET_KEY	Django's secret key for cryptographic signing. Must be set in production.	A default insecure key	becathlon/settings.py:28-28
DEBUG	Toggles Django's debug mode. Should be 'False' in production.	'True'	becathlon/settings.py:31-31
ALLOWED_HOSTS	A comma-separated string of host/domain names this site can serve.	'localhost,127.0.0.1,testserver'	becathlon/settings.py:33-33
DB_NAME	The name of the PostgreSQL database.	None	becathlon/settings.py:112-112
DB_USER	The PostgreSQL database user.	None	becathlon/settings.py:113-113
DB_PASSWORD	The password for the PostgreSQL user.	None	becathlon/settings.py:114-114
DB_HOST	The host of the PostgreSQL database.	None	becathlon/settings.py:115-115
DB_PORT	The port for the PostgreSQL database.	None (defaults to 5432)	becathlon/settings.py:116-116
SCHEMA	The PostgreSQL schema to use.	None	becathlon/settings.py:117-117

Database Configuration Logic

The application can switch between a PostgreSQL database for production and an SQLite database for local development. The logic in settings.py checks for the presence of PostgreSQL environment variables to make this decision.

This diagram illustrates the database configuration flow.

Production Security Settings

When DEBUG is False, several security enhancements are enabled. If you are having issues with cookies or CSRF in a production-like environment, verify these settings.

• SESSION_COOKIE_SECURE = True
• CSRF_COOKIE_SECURE = True
• CSRF_TRUSTED_ORIGINS: This list must include the domain from which your application is served to avoid 403 errors on POST requests.

Sources: becathlon/settings.py:36-49, becathlon/settings.py:41-45

Database Issues

Database problems can arise from migration conflicts or data corruption. The project includes scripts and standard Django commands to manage the database state.

Full Database Reset (Production)

For catastrophic issues in a production environment where a full reset is permissible, the reset_production_db.py script provides a powerful but destructive tool.

Warning: This script will delete all data in the configured PostgreSQL database.

The script performs the following actions:

1. Prompts the user for explicit confirmation.
2. Connects to the database and drops all existing tables.
3. Runs manage.py migrate to recreate the database schema from scratch.
4. Seeds the database with initial ProductTypes.

This flowchart shows the process of the reset_database function.

Standard Migrations

For routine schema changes, use the standard Django migration commands. The deployment script runs migrations automatically.

• python manage.py makemigrations
• python manage.py migrate

The deployment script specifically calls python manage.py migrate --noinput.
Sources: pbp-deploy.sh:16-16

Deployment Problems

Deployment issues often relate to static files, database migrations, or environment configuration.

Deployment Script Flow

The pbp-deploy.sh script automates the deployment process. Understanding its flow is key to diagnosing failures.

This diagram shows the steps executed by the deployment script.

Static File Issues

If CSS or JavaScript files are not loading in production (resulting in a broken UI), check the following:

1. collectstatic Command: Ensure python manage.py collectstatic runs successfully during deployment. This command gathers all static files into the STATIC_ROOT directory.
2. WhiteNoise Configuration: The project uses WhiteNoise to serve static files in production.
   • whitenoise.middleware.WhiteNoiseMiddleware should be in MIDDLEWARE.
   • The STORAGES["staticfiles"]["BACKEND"] is set to whitenoise.storage.CompressedStaticFilesStorage. This can sometimes cause issues if files are missing. The comments suggest that CompressedManifestStaticFilesStorage was avoided due to potential 500 errors.

Sources: pbp-deploy.sh:12-13, becathlon/settings.py:90-91, becathlon/settings.py:182-192

Frontend and AJAX Issues

The homepage uses AJAX extensively to load, add, and delete products. Failures in these features are often due to JavaScript errors, incorrect API endpoints, or CSRF protection.

AJAX Endpoints

The following API endpoints are defined for frontend interactions:

Method	Endpoint	Description	Source
GET	/api/products/	Fetches a paginated and filterable list of products.	apps/main/templates/main/home.html:325-337, IMPLEMENTATION.md:52-52
POST	/api/products/add/	Adds a new product. Requires authentication and a "SELLER" account type.	apps/main/templates/main/home.html:388-400, IMPLEMENTATION.md:53-53
DELETE	/api/products/<id>/delete/	Deletes a product. Requires authentication and ownership of the product.	apps/main/templates/main/home.html:413-425, IMPLEMENTATION.md:54-54

CSRF Token Handling

All POST and DELETE requests require a CSRF token. The frontend JavaScript retrieves this token from the cookies.

// apps/main/templates/main/home.html:298-312
function getCookie(name) {
    let cookieValue = null;
    if (document.cookie && document.cookie !== '') {
        const cookies = document.cookie.split(';');
        for (let i = 0; i < cookies.length; i++) {
            const cookie = cookies[i].trim();
            if (cookie.substring(0, name.length + 1) === (name + '=')) {
                cookieValue = decodeURIComponent(cookie.substring(name.length + 1));
                break;
            }
        }
    }
    return cookieValue;
}
const csrftoken = getCookie('csrftoken');

This token is then included in the request headers as X-CSRFToken. A failure to do so will result in a 403 Forbidden error.
Sources: apps/main/templates/main/home.html:298-312, apps/main/templates/main/home.html:394-397, apps/main/templates/main/home.html:418-420

AJAX Deletion Flow

This sequence diagram illustrates the process of deleting a product from the homepage.

Running Tests for Verification

A primary troubleshooting step is to run the project's test suite to ensure the backend logic is functioning as expected. The project aims for 90% test coverage.

Test Commands

The following commands, found in the README.md, can be used to run tests and check coverage.

Command	Description
coverage run --source='apps' manage.py test; coverage report	Runs all tests for all apps and generates a coverage report.
coverage run --source='apps/<app_name>' manage.py test apps.<app_name>	Runs tests for a specific app.

Sources: README.md:120-123

Running these tests can help isolate issues. For example, if tests for the main app fail, it might indicate a problem with the product models or the AJAX view logic. The tests in apps/main/tests.py cover model creation, view responses, and the behavior of AJAX endpoints for adding and deleting products.
Sources: apps/main/tests.py