Modular, scalable Django starter with HTMX, Hyperscript, Redis, and ManticoreSearch. Pre-configured for rapid development with CRUD mixins, async tasks, and 2FA security. 🚀
Go to file
2025-02-07 22:12:25 +00:00
app Renew with 2FA and Podman 2025-02-07 21:53:52 +00:00
core Renew with 2FA and Podman 2025-02-07 21:53:52 +00:00
docker Renew with 2FA and Podman 2025-02-07 21:53:52 +00:00
.gitignore Improve README 2025-02-07 22:06:59 +00:00
docker-compose.yml Renew with 2FA and Podman 2025-02-07 21:53:52 +00:00
Dockerfile Switch to UWSGI and make docker build/run smarter 2022-10-18 07:22:22 +01:00
Makefile Renew with 2FA and Podman 2025-02-07 21:53:52 +00:00
manage.py Initial commit 2022-10-12 07:22:22 +01:00
README.md Remove template tag example 2025-02-07 22:12:25 +00:00
requirements.txt Renew with 2FA and Podman 2025-02-07 21:53:52 +00:00
stack.env.example Renew with 2FA and Podman 2025-02-07 21:53:52 +00:00

🚀 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 Djangos 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.

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! 🚀