app | ||
core | ||
docker | ||
.gitignore | ||
docker-compose.yml | ||
Dockerfile | ||
Makefile | ||
manage.py | ||
README.md | ||
requirements.txt | ||
stack.env.example |
🚀 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.
-
Clone the repository
❯ git clone https://git.zm.is/XF/envelope ❯ cd envelope
-
Set up the environment variables
❯ cp stack.env.example stack.env
-
Edit
stack.env
-
Build and start the containers
❯ make build ❯ make run
-
Run database migrations
❯ make migrate
-
Create a superuser for Django Admin (optional but recommended)
❯ make auth
-
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! 🚀