Development Guide

This guide covers how to set up the project locally, run common tasks, and understand the project structure.

Prerequisites

• Docker & Docker Compose: Required for the Postgres Database.
• Node.js 24: For frontend asset management.
• Python 3.13: The project runtime.
• Poetry: For Python dependency management.

Initial Setup

1. Install Dependencies:

   poetry install --with dev,docs,test --no-root
   npm ci

2. Start Database:

   inv up --build  # Build and start containers

3. Run Migrations & Create Superuser:

   The inv up command handles the database container, but you might need to apply migrations manually the first time or if you reset the DB.

   poetry run python manage.py migrate
   inv createsuperuser  # Creates root@example.com / password

4. Start Development Server:

   inv start

   This uses Honcho to run the Django dev server and Webpack simultaneously (defined in Procfile.dev). Access the site at http://127.0.0.1:8000.

Common Tasks

We use Invoke to manage common development tasks. Defined in tasks.py.

Server & Infrastructure

Command	Description
inv start	Run the full dev stack (Django + Webpack)
inv dev	Run only the Django development server
inv up	Start Docker containers (add --build to rebuild)
inv stop	Stop Docker containers
inv down	Stop and remove containers (add --volumes to wipe data)
inv logs [container]	View logs (e.g., inv logs db -f)
inv exec [container] [cmd]	Execute command in container

Database Management

Command	Description
inv db-snapshot [prefix]	Create a local DB snapshot using DSLR
inv backup-db	Create a .dump backup in ./.backups
inv restore-db [file]	Restore a database dump file
inv createsuperuser	Create a dev superuser (root@example.com / password)

Code Quality & Testing

Command	Description
inv test	Run pytest
inv lint	Check code style with Ruff and Black
inv lint --fix	Auto-format code
inv clean-pyc	Remove Python file artifacts

Release Management

Command	Description
inv bump [branch]	Bump version and generate changelog (uses Commitizen & standard-version)

Configuration

The project uses django-environ to manage settings. Key environment variables (set in .env):

General

• DEBUG: Enable debug mode (default: False).
• django_secret_key: Django secret key.
• DATABASE_URL: Postgres connection string.

Security (Cloudflare Turnstile)

See Turnstile Integration for setup instructions and keys.

Notifications & SMS

• NOTIFICATION_REMINDER_DAYS: Comma-separated list of days before duty to send reminders (e.g., 1,3,7).
• DEFAULT_DOMAIN: Domain used in notification links (default: embc.cc).
• XYNLE_API_KEY: API Key for Xynle SMS.
• XYNLE_API_USERNAME: Username for Xynle SMS.
• XYNLE_API_SECRET: Secret/Password for Xynle SMS.
• XYNLE_API_SENDER_ID: Sender ID for SMS (e.g., EMBC).

Site Info

• SITE_NAME: Name of the site (default: "EmBC").
• SITE_LOCATION: Physical location (default: "Emmasdale Baptist Church").
• SITE_AUTHOR: Author name (default: "Emmasdale Baptist Church").

Project Structure

The project follows a standard Django layout with a few custom apps in obed/:

obed/
├── core/           # Common utilities (Email, PDF, SMS)
├── home/           # Landing page
├── notifications/  # Notification logic (Queues, Service)
├── schedules/      # Main logic: Schedules, Assignments, Dates
├── stewards/       # Member management (Steward profiles)
├── users/          # Custom User model (Auth)
└── settings/       # Django settings (Base, Dev, Prod)