diff --git a/.gitignore b/.gitignore index 84f814e..3bbb062 100644 --- a/.gitignore +++ b/.gitignore @@ -157,3 +157,5 @@ cython_debug/ .vscode/ core/static/admin core/static/debug_toolbar +docker/data/ +static/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml deleted file mode 100644 index 23c9d5b..0000000 --- a/.pre-commit-config.yaml +++ /dev/null @@ -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 diff --git a/README.md b/README.md index 9cd4b09..28399aa 100644 --- a/README.md +++ b/README.md @@ -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. -```shell -$ python3 -m venv env -$ source env/bin/activate -(env) $ pip install -r docker/prod/requirements.prod.txt +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 + ❯ git clone https://git.zm.is/XF/envelope + ❯ cd envelope + ``` + +2. Set up the environment variables + ```shell + ❯ cp stack.env.example stack.env + ``` + +3. Edit `stack.env` + +4. Build and start the containers + ```shell + ❯ make build + ❯ make run + ``` + +5. Run database migrations + ```shell + ❯ make migrate + ``` + +6. Create a superuser for Django Admin (optional but recommended) + ```shell + ❯ make auth + ``` + +7. Monitor logs + ```shell + ❯ 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: + ```shell + ❯ docker-compose --env-file=stack.env run --rm app sh -c ". /venv/bin/activate && python manage.py " + ``` + +## πŸ›‘ Stopping the Project +To stop all running services: + ```shell + ❯ 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/; +} ``` -## 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 -``` +## πŸ”„ 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. | -## 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. +## πŸ”§ Additional Configuration +### Django Environment Variables -## Running database migrations -Now we need to run the database migrations in order to get a working database. -```shell -(env) $ python manage.py migrate -``` -Note that these are automatically run by a step in the compose file in production. -You won't need to do that manually. +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 + ``` -## Creating a superuser -In order to access Django admin, we need a superuser. -```shell -(env) $ python manage.py createsuperuser -Username: t2 -Email address: t2@google.com -Password: -Password (again): -Superuser created successfully. -``` +These can be set inside `stack.env`. -## Running -The Docker Compose file is located in `docker/docker-compose.prod.yml`. -There is a shortcut to run it: `make run`. +## ⚠️ Legal Disclaimer +**This software is provided as-is, without warranty.** -## Stopping -To stop the containers, run `make stop`. +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. -## Setup -This setup may be different from what you've seen before. +This template is for educational and development purposes only. **Ensure compliance with all relevant legal and security standards before deployment.** -### 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. - -### Nginx -Nginx runs in the `nginx` container and proxies requests to Uvicorn thanks to a mounted and shared directory. No TCP required. - -### Pre-start steps -There's a few commands running before start to ensure Django works correctly. - -#### Migration -The `migration` container step runs the migrations so you don't need to remember to do it. - -#### 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. +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! πŸš€ \ No newline at end of file