XF/envelope
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Improve README

Browse Source
This commit is contained in:
Mark Veidemanis
2025-02-07 22:06:59 +00:00
parent 83a3761d17
commit c9dd0c1282
3 changed files with 150 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@@ -157,3 +157,5 @@ cython_debug/
.vscode/
core/static/admin
core/static/debug_toolbar
docker/data/
static/

30
.pre-commit-config.yaml
View File

@@ -1,30 +0,0 @@
repos:
- repo: https://github.com/psf/black
rev: 23.1.0
hooks:
- id: black
exclude: ^core/migrations
- repo: https://github.com/PyCQA/isort
rev: 5.11.5
hooks:
- id: isort
args: ["--profile", "black"]
- repo: https://github.com/PyCQA/flake8
rev: 6.0.0
hooks:
- id: flake8
args: [--max-line-length=88]
exclude: ^core/migrations
- repo: https://github.com/rtts/djhtml
rev: v2.0.0
hooks:
- id: djhtml
args: [-t 2]
- id: djcss
exclude : ^core/static/css # slow
- id: djjs
exclude: ^core/static/js # slow
- repo: https://github.com/sirwart/ripsecrets.git
rev: v0.1.5
hooks:
- id: ripsecrets

188
README.md
View File

@@ -1,64 +1,158 @@
# Envelope
Template Django app.
# 🚀 Django Starter Template
## Setting up the environment
Create the virtual environment, enable it, and install the dependencies.
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](https://git.zm.is/XF/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 like `has_plan`, `joinsep`, and `urlsafe`.
- **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**
```shell
$ python3 -m venv env
$ source env/bin/activate
(env) $ pip install -r docker/prod/requirements.prod.txt
❯ git clone https://git.zm.is/XF/envelope
❯ cd envelope
```
## Local settings
You'll need to copy the `app/local_settings.example.py` file to `app/local_settings.py`. The project won't start otherwise.
```
$ cp app/local_settings.example.py app/local_settings.py
```
## stack.env
The stack.env file referenced is a Portainer special. This is where Portainer would put a file containing all the environment variables set up in its UI.
To run it manually, you will need to copy `stack.env.example` to `stack.env` in the project root.
## Running database migrations
Now we need to run the database migrations in order to get a working database.
2. Set up the environment variables
```shell
(env) $ python manage.py migrate
❯ cp stack.env.example stack.env
```
Note that these are automatically run by a step in the compose file in production.
You won't need to do that manually.
## Creating a superuser
In order to access Django admin, we need a superuser.
3. Edit `stack.env`
4. Build and start the containers
```shell
(env) $ python manage.py createsuperuser
Username: t2
Email address: t2@google.com
Password:
Password (again):
Superuser created successfully.
❯ make build
❯ make run
```
## Running
The Docker Compose file is located in `docker/docker-compose.prod.yml`.
There is a shortcut to run it: `make run`.
5. Run database migrations
```shell
❯ make migrate
```
## Stopping
To stop the containers, run `make stop`.
6. Create a superuser for Django Admin (optional but recommended)
```shell
❯ make auth
```
## Setup
This setup may be different from what you've seen before.
7. Monitor logs
```shell
❯ make log
```
### Uvicorn
There is a Uvicorn worker in the `app` container listening on `/var/run/socks/app.sock`. This is the bit that runs the actual code.
## ⚙️ 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. |
### Nginx
Nginx runs in the `nginx` container and proxies requests to Uvicorn thanks to a mounted and shared directory. No TCP required.
## 🔥 Running Commands in a Container
### Pre-start steps
There's a few commands running before start to ensure Django works correctly.
You can execute management commands inside the app container using:
```shell
❯ docker-compose --env-file=stack.env run --rm app sh -c ". /venv/bin/activate && python manage.py <command>"
```
#### Migration
The `migration` container step runs the migrations so you don't need to remember to do it.
## 🛑 Stopping the Project
To stop all running services:
```shell
❯ make stop
```
#### Collectstatic
The `collectstatic` container step collects all static files from plugins and puts them in the `core/static` folder. This folder is served straight from Nginx without going through Uvicorn.
## 🕵️‍♂️ 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:
```shell
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! 🚀