Django Quick Starter with Celery and MongoDB 🚀🐍

Technology Stack

This is a Django starter template pre-configured with Celery for handling asynchronous tasks and MongoDB as the message broker. It provides a robust foundation to quickly start your Django project, with necessary configurations for both the backend and asynchronous task processing.

Requirements

• Ensure you have uv installed

• Ensure you have node installed and pnpm Here are the official websites for the technologies you mentioned:

For help checkout this article

Installation Guide 🔧

Clone the Repository 📂

Clone the repository to your local machine:

git clone https://github.com/dlion4/django-quick-starter.git

Frontend Setup 🎨

1. Installation ⚙️

pnpm install

2. Running the Application 🚀

# In development mode
pnpm run dev

# In production mode
pnpm run build

---

Backend Setup 🔧

Step 1: Create a Virtual Environment 🌱

Set up a virtual environment to isolate dependencies for your project:

uv venv && .\.venv\Scripts\activate
# On Windows: .\.venv\Scripts\activate
# On Linux/MacOS: source .venv/Scripts/activate

uv add setuptools --dev

Step 2: Install Required Dependencies 📦

Install all required dependencies listed in the requirements.txt:

uv add -r requirements.txt

# You can still use pip but we recommend using uv for fast development

Step3: Environment Variables setup

Ensure you have all of these variables in place

DJANGO_SECRET_KEY=
DATABASE_URL=
DJANGO_ALLOWED_HOSTS=
DJANGO_DEBUG=False

#AWS MEDIA STORAGE (optional)
DJANGO_AWS_ACCESS_KEY_ID=""
DJANGO_AWS_SECRET_ACCESS_KEY=""
DJANGO_AWS_STORAGE_BUCKET_NAME=""

# REDIS STORAGE (optional)
REDIS_URL=
CELERY_BROKER_URL=
CELERY_RESULT_BACKEND=
# SENTRY PROFILING (optional)
SENTRY_DSN=

# Social Authentication
OAUTH2_GOOGLE_CLIENT_ID=
OAUTH2_GOOGLE_CLIENT_SECRET=

---

Database & Celery Setup 🗄️⚙️

Celery in this project can use MongoDB as the default broker, but you may also configure Redis as an alternative (via WSL on Windows) or TinyDB for lightweight testing.

---

Option 1: MongoDB (Default) 🗄️

Step 1: Install MongoDB Follow the official MongoDB installation guide for your operating system: 👉 MongoDB Installation Guide

Once installed, ensure MongoDB is running on your machine.

Step 2: Configure Celery Celery is configured in config/celery.py.

# config/celery.py
from __future__ import absolute_import, unicode_literals
import os
from celery import Celery

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings.production')

app = Celery('config')
app.config_from_object('django.config:settings', namespace='CELERY')
app.autodiscover_tasks()

Set the MongoDB connection string in your production.py:

# production.py

# Celery configuration
CELERY_BROKER_URL = env.str("MONGODB_URL")  # e.g. mongodb://localhost:27017/db_name
CELERY_RESULT_BACKEND = CELERY_BROKER_URL

---

Option 2: Redis via WSL 🐧

If MongoDB gives issues, you can switch to Redis:

1. Install WSL (Windows Subsystem for Linux): 👉 Install WSL Guide

2. Install Redis inside WSL:

   sudo apt update
   sudo apt install redis-server

3. (Optional) Install RedisInsight for GUI management:

   👉 Download RedisInsight

4. Update production.py:

# production.py

CELERY_BROKER_URL = env.str("REDIS_URL")  # e.g. redis://localhost:6379/0
CELERY_RESULT_BACKEND = CELERY_BROKER_URL

---

Option 3: TinyDB (Lightweight Testing Only) 📦

If you just need quick testing without MongoDB/Redis: 👉 TinyDB Documentation

⚠️ Note: TinyDB is not recommended for production, but can be used in local/dev environments.

Note: Replace "MONGODB_URL" with your MongoDB URL (e.g., mongodb://localhost:27017/db_name).

---

Running the Application 🏃‍♂️

Step 1: Migrate the Database 🗃️

Run migrations to set up the database:

rav run db

Step 2: Start the Django Development Server 🌐

Start the Django development server:

python manage.py runserver

Step 3: Start Celery Worker 🧑‍💻

Start the Celery worker to process background tasks:

rav run celery

Step 4: Start Celery Beat (optional) ⏰

If you are using Celery Beat to schedule periodic tasks (set to run by default), run it in another terminal:

rav run beat

Step 5: Start Celery Flower (optional) 🌸

To monitor Celery tasks and workers, you can use Flower:

rav run flower

---

Example Celery Task 💡

To define a Celery task in any of your Django app's tasks.py files:

1. Create a task in core/tasks.py:

   from celery import shared_task
   
   @shared_task
   def my_celery_task():
       # Your task logic here
       print("Task executed!")
       return "Hello from Celery!"

2. Invoke the task asynchronously from anywhere in your Django code:

from core.tasks import my_celery_task

# Call the task
my_celery_task.delay()

You can also login to the django admin and then setup the periodic task if you wish to. video walkthrough

---

Testing Celery with MongoDB 🔍

Once everything is set up, test your Celery tasks by calling the my_celery_task. If everything is configured correctly, you should see "Task executed!" in the Celery worker terminal output.

---

Troubleshooting ⚠️

• Celery not connecting to MongoDB?

  • Ensure MongoDB is running: sudo systemctl status mongod.
  • Double-check the CELERY_BROKER_URL in settings.py is set correctly.
  • Ensure the CELERY_TASK_POOL="solo" In windows as billiard has permission errors. This is however useful in development. Use billiard in production

• Celery worker not processing tasks?

  • Make sure the Celery worker is running with the correct log level: celery -A your_project worker --loglevel=info.
  • Check the Celery logs for any errors or issues.

---

Sure! Here's the Testing section with some added emojis to make it more engaging:

Testing 🧪

This project uses pytest for running tests, coverage for measuring test coverage, and mypy for type checking. Below are the instructions for using each tool.

1. Running Tests with pytest 🧑‍🔬

To run the tests, you can use pytest, a testing framework that will automatically discover and run all the tests in your project.

Installing pytest

If you haven't installed pytest yet, install it by running:

pip install pytest

Running Tests

You can run all tests by simply executing the following command:

pytest

This will automatically discover and execute all test functions in the project.

Running Specific Tests

You can also run a specific test file or function by providing the path to the test file:

pytest path/to/test_file.py

To run a specific test function within a test file:

pytest path/to/test_file.py::test_function_name

2. Running Tests with Coverage 📊

If you want to check the test coverage, you can use pytest-cov. This allows you to see which lines of code are covered by the tests.

Installing pytest-cov

To install pytest-cov, run the following command:

pip install pytest-cov

Running Tests with Coverage

To run the tests with coverage reporting, use this command:

pytest --cov=<your_project_module> --cov-report=term

Replace <your_project_module> with the name of your project module or app (e.g., core, api, etc.). This will display a coverage report in the terminal.

Generating a Coverage Report (Optional)

If you want to save the coverage report to a file (e.g., coverage.xml), use the following command:

pytest --cov=<your_project_module> --cov-report=xml

This will generate a coverage.xml file that can be used for integration with CI services like GitLab or GitHub Actions.

3. Running Type Checking with mypy 🔍

To ensure type safety in your project, mypy is used for static type checking.

Installing mypy

If you haven't installed mypy yet, run the following:

pip install mypy

Running mypy

To run mypy and check for type errors in your project, run the following command:

mypy .

This will check all Python files in your project for type issues. You can specify a specific file or directory to check by providing its path:

mypy path/to/file.py

4. Running mypy with Coverage 🏆

You can also run mypy in conjunction with pytest and coverage to ensure that your code is both properly tested and typed.

Example Command

pytest --cov=<your_project_module> --cov-report=term && mypy .

This command will first run your tests and measure coverage, then it will run mypy to check for type errors.

5. Continuous Integration (CI) 🤖

You can integrate pytest, coverage, and mypy into your continuous integration pipeline (e.g., GitHub Actions, GitLab CI). Below is an example of how to set this up using GitHub Actions.

Example GitHub Action for Running Tests and Coverage

Create a .github/workflows/test.yml file in your repository with the following contents:

name: Django CI

on:
  push:
    branches: [ "dev" ]
  pull_request:
    branches: [ "dev" ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Set up Python 3.11
      uses: actions/setup-python@v3
      with:
        python-version: 3.11
    - name: Install Dependencies
      run: |
        pip install -r requirements.txt
    - name: Run tests with coverage
      run: |
        base -c "coverage run -m pytest -rP && coverage report"

    - name: Run mypy for type checking
      run: mypy

  build:
    runs-on: ubuntu-latest
    strategy:
      max-parallel: 4
      matrix:
        python-version: [3.7, 3.8, 3.9, 3.11]

    steps:
    - uses: actions/checkout@v4
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v3
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install Dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
    - name: Build Artifacts
      run: |
        uv build

This GitHub Action will run pytest with coverage and mypy every time you push or create a pull request to the main branch.

Writing Tests ✍️

To write a new test, create a new test file in the tests/ directory. Test files should follow the naming convention test_*.py to be automatically discovered by pytest.

Example of a simple test:

def test_addition():
    assert 1 + 1 == 2

Mocking and Fixtures 🧩

If your tests need to set up some initial state or mock external services, you can use fixtures. Here's an example of a fixture that sets up a mock database:

import pytest

@pytest.fixture
def mock_db():
    db = Database()
    yield db
    db.close()

You can then use this fixture in your tests:

def test_database_query(mock_db):
    result = mock_db.query("SELECT * FROM users")
    assert len(result) > 0

Test Results 🎯

After running the tests, you can check the terminal output to see if all tests passed. If a test fails, pytest will display detailed information about the error, including the file and line number where the failure occurred.

---

License 📄

This project is licensed under the MIT License - see the LICENSE file for details.

Credits 🎓

• Django - A high-level Python web framework.
• Celery - An asynchronous task queue/job queue system.
• MongoDB - A NoSQL database used as the message broker for Celery.

---

Additional Resources 📚

• Django Documentation
• Celery Documentation
• MongoDB Documentation
• Webpack Documentation

---