Yana Backend

This guide explains how to set up the development environment for the yana-back Django application, configure a pre-commit hook to enforce standardized commit messages, run the server locally, and use Docker to containerize the application.

Prerequisites

Before starting, ensure the following are installed and configured:

• Python 3.7 or higher: Required for the application, validation script, and pre-commit.
• Git: Needed for version control and commit operations.
• pip: Python package manager, typically included with Python.
• Docker: Required for building and running the containerized application.
• Virtual environment (recommended): To isolate dependencies and avoid conflicts.

1. Set Up the Development Environment

1.1 Create and Activate a Virtual Environment

A virtual environment keeps dependencies isolated and is highly recommended.

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Windows
venv\Scripts\activate

# On Linux/macOS
source venv/bin/activate

Note: After activation, your terminal prompt should show (venv).

1.2 Install Pre-Commit

Install the pre-commit package to manage commit validation hooks.

pip install pre-commit

Verification: Check the installed version to confirm:

pre-commit --version

2. Configure the Commit Message Validation Hook

The pre-commit hook ensures all commit messages follow the Conventional Commits format (<type>: <description>, where <type> is feat, chore, or fix).

2.1 Create the Validation Script

The script checks commit message format and blocks invalid commits.

• File Path: .github/scripts/check_commit_message.py
• Permissions (Linux/macOS): Ensure the script is executable:

  chmod +x .github/scripts/check_commit_message.py

2.2 Configure the Pre-Commit Hook

Define the hook in a configuration file to integrate with pre-commit.

• File Path: .pre-commit-config.yaml (place in the project root)

3. Install and Test the Hook

3.1 Install the Hook

• Install the pre-commit hook to validate commit messages automatically:

pre-commit install --hook-type commit-msg

3.2 Test the Hook

Test the hook to ensure it enforces the correct format.

• Commit Test:

  git commit -m "feat: add test file"

• Try an invalid message:

  git commit -m "bad message"

  The hook will block invalid commits and show valid examples.

4. Run the Server Locally

To run the Django application locally for development:

• Install dependencies:

  pip install -r requirements.txt

• Start the server:

  python3 site_app/manage.py runserver

  Access the app at http://localhost:8000.

4.1 Dockerfile Overview

The Dockerfile is a script that builds a Docker image for the Django app.

• What It Does:

  • Starts with a Python base image to install dependencies.
  • Copies the app code and a startup script (start.py).
  • Creates a minimal, secure image for running the app with Gunicorn.
  • Runs the server on port 8000 by default.

• Environment Variables: The application requires specific configuration settings to connect to a database and secure the app. These settings are provided as environment variables. The repository includes a .env.example file with the required variables:

  DB_NAME=
  DB_USER=
  DB_PASSWORD=
  DB_HOST=
  DB_PORT=
  SECRET_KEY=
  

  To configure the app:

  1. Copy .env.example to a new file named .env (Linux/macOS):

     cp .env.example .env

  2. Open .env in a text editor and fill in the values for each variable (e.g., database name, user, password, host, port, and a secure secret key).
  3. Save the .env file and keep it secure (do not commit it to Git).

• Usage: Build and run the Docker container, passing the environment variables from the .env file:

  # Build the Docker image
  docker build -t yana-back .
  
  # Run the container with the .env file
  docker run -dp 8000:8000 --env-file .env yana-back

  Access the app at http://localhost:8000.

4.2 .dockerignore Overview

The .dockerignore file lists files and folders to exclude from the Docker image, keeping it small and secure.

• What It Excludes:

  • Documentation (e.g., README.md).
  • Git files (e.g., .git, .gitignore).
  • Virtual environments (e.g., venv/, .venv/).
  • Python caches (e.g., __pycache__/, *.pyc).
  • Development files (e.g., .pytest_cache/, *.log).
  • Configuration files (e.g., .pre-commit-config.yaml, .github/workflows/).

• Why It’s Important:

  • Reduces image size.
  • Improves build speed.
  • Prevents sensitive files from being included.

5. Additional Documentation

In addition to this README, make sure to review the following important documentation for a complete understanding of the project setup and workflows:

• .github/workflows/README.md: Details the CI/CD pipeline configuration and workflows for automated testing and deployment.
• .github/scripts/README.md: Explains the purpose and usage of scripts used in the project, including the commit message validation script.