🚀 Django Starter Template

A lightweight, production-ready Django template for rapid project development.

📌 Features

• Django 4+ with Modular Structure: A clean, scalable, and extensible architecture for fast development.
• Pre-configured Podman & Docker Support: Seamlessly deploy using containerized environments.
• ManticoreSearch & Redis Integration (Optional): Enhanced search and caching capabilities for high-performance applications.
• Multi-Agent Execution: Supports processing, scheduling, and background task handling via Django management commands.
• Automated Migrations & Static File Handling: Database migrations and collectstatic are run automatically before deployment.
• Built-in Django Admin & Authentication: User authentication, registration, and two-factor authentication (2FA) ready.
• HTMX & Hyperscript Powered UI: Provides a dynamic and responsive frontend with lightweight interactivity.
• Bulma-Based UI with Rich Components: Pre-integrated Bulma CSS framework, tooltips, sliders, calendars, and grid-based layouts.
• Chart.js & Data Visualization: Easily generate and display interactive charts and graphs.
• Modular Notifications System: Supports email, in-app, and third-party notifications with extensible notify.py.
• Integrated Background Task Management: Built-in support for scheduling and executing tasks asynchronously.
• Security Enhancements: Includes Two-Factor Authentication (2FA) via Django’s two_factor package.
• Easy Integration with django-crud-mixins: Rapidly create CRUD operations with minimal code.
• Built-in Support for Django Signals: Process real-time events and system hooks efficiently.
• Custom Django Template Tags: Extend template functionality with built-in utilities.
• Custom Django Views & Permissions Management: Pre-configured base views, notifications, and access control utilities.
• Manifest & PWA Support: Adds Progressive Web App (PWA) capabilities with a manifest file and service worker support.

---

🚀 Quickstart Guide

🔧 Setting Up the Environment

Ensure you have Podman or Docker installed.

1. Clone the repository

   ❯ git clone https://git.zm.is/XF/envelope
   ❯ cd envelope
   

2. Set up the environment variables

   ❯ cp stack.env.example stack.env
   

3. Edit stack.env

4. Build and start the containers

   ❯ make build
   ❯ make run
   

5. Run database migrations

    ❯ make migrate
   

6. Create a superuser for Django Admin (optional but recommended)

   ❯ make auth
   

7. Monitor logs

   ❯ make log
   

⚙️ Deployment & Architecture

🏗️ Services Overview

Service	Description
app	Main application container running Uvicorn for API handling.
db	ManticoreSearch-based database backend.
redis	Message queue for task distribution.
signal-cli	Handles Signal communications.
processing	Processes streams.
scheduling	Handles timed tasks.
migration	Runs database migrations automatically on startup.
collectstatic	Collects static files for Django before launch.

🔥 Running Commands in a Container

You can execute management commands inside the app container using:

❯ docker-compose --env-file=stack.env run --rm app sh -c ". /venv/bin/activate && python manage.py <command>"

🛑 Stopping the Project

To stop all running services:

❯ make stop

🕵️‍♂️ Operational Modes

The app runs in different operation modes set via OPERATION:

Mode	Description
uwsgi	Runs behind Nginx for production.
dev	Direct execution via Django's built-in server (development mode).

The default Podman entrypoint dynamically selects the correct process based on OPERATION. Be sure to uncomment nginx if using dev, as the shipped setup expects an external nginx instance to point to the app's uwsgi sock:

location / {
    include include/xf-only.conf;
    include     /etc/nginx/uwsgi_params;
    uwsgi_pass  unix:///code/run/uwsgi.sock;
    uwsgi_param Host $host;
    uwsgi_param X-Real-IP $remote_addr;
    uwsgi_param X-Forwarded-For $proxy_add_x_forwarded_for;
    uwsgi_param X-Forwarded-Proto $http_x_forwarded_proto;
}
location /static {
    alias /code/xf/envelope/static/;
}

🔄 Persistent Data & Storage

Mount Path (Host)	Purpose
docker/uwsgi.ini	Configuration for uWSGI execution.
db.sqlite3	SQLite database storage.
/code/vrun/	Sockets shared between services.
signal-cli-config/	Stores Signal CLI configuration and keys.

🔧 Additional Configuration

Django Environment Variables

The following are required for proper operation:

 APP_PORT=5006
 REPO_DIR=.
 APP_LOCAL_SETTINGS=./app/local_settings.py
 APP_DATABASE_FILE=./db.sqlite3
 DOMAIN=example.com
 URL=https://example.com
 ALLOWED_HOSTS=example.com
 NOTIFY_TOPIC=example-topic
 CSRF_TRUSTED_ORIGINS=https://example.com
 DEBUG=y
 SECRET_KEY=
 STATIC_ROOT=/code/static
 REGISTRATION_OPEN=0
 OPERATION=uwsgi
 BILLING_ENABLED=0

These can be set inside stack.env.

⚠️ Legal Disclaimer

This software is provided as-is, without warranty.

By using this Django template, you agree that:

• You are responsible for your own configurations and security setup.
• The authors disclaim all liability for damages resulting from its use.

This template is for educational and development purposes only. Ensure compliance with all relevant legal and security standards before deployment.

This serves as a ready-to-use Django starter kit with a structured setup for quick deployment. Let me know if you want additional tweaks! 🚀