164 lines
9.1 KiB
Markdown
164 lines
9.1 KiB
Markdown
# Portable Django + Vite integration
|
|
|
|
This repository originally used only Django native static files. The Vite integration below is now wired into the rendered public pages and custom Admin pages: shared assets live in `frontend/src/`, while Django still owns template rendering and its native static files.
|
|
|
|
## What is included
|
|
|
|
- `vite_integration/`: reusable Django app and `{% vite_asset %}` tag
|
|
- `frontend/src/entries/`: one Vite entry module per rendered page, with shared `styles/` and `scripts/` modules
|
|
- `vite.config.mjs`: Vite output, manifest, host, port, and entry configuration
|
|
- `package.json`: `dev`, `django`, `vite`, and `build` scripts
|
|
- `scripts/dev-django.mjs`: configurable backend process for `concurrently`
|
|
- `.env.vite.example`: documented development and production variables
|
|
|
|
Vite builds into `vite_integration/static/vite/`. Because this is a Django app static directory, Django's staticfiles finders and `collectstatic` discover the manifest and built assets automatically.
|
|
|
|
## Prerequisites
|
|
|
|
- Python and the Django environment for the project
|
|
- Node.js 20+ and npm
|
|
- A configured Django `STATIC_URL` and `STATIC_ROOT` for production
|
|
|
|
## Install in this repository
|
|
|
|
```sh
|
|
cp .env.vite.example .env.vite
|
|
npm install
|
|
set -a; . ./.env.vite; set +a
|
|
npm run dev
|
|
```
|
|
|
|
`npm run dev` starts Django and Vite together using `concurrently`. It runs `python manage.py runserver 127.0.0.1:8000` and Vite on `127.0.0.1:5173` by default. Change the variables before starting it, or set `DJANGO_DEV_COMMAND` to replace the backend command completely.
|
|
|
|
## Add an entry point to a template
|
|
|
|
Choose an entry point and include it once in the relevant base template:
|
|
|
|
```django
|
|
{% load vite %}
|
|
{% vite_asset "frontend/src/entries/site.js" %}
|
|
```
|
|
|
|
The tag renders Vite's HMR client and the entry point when `VITE_USE_DEV_SERVER=true`. Otherwise it reads Vite's manifest and renders the fingerprinted CSS and JavaScript under Django's static URL. See `vite_integration/templates/vite_integration/example_assets.html` for the same snippet.
|
|
|
|
## Production
|
|
|
|
```sh
|
|
set -a; . ./.env.vite; set +a
|
|
VITE_USE_DEV_SERVER=false npm run build
|
|
VITE_USE_DEV_SERVER=false python manage.py collectstatic --noinput
|
|
```
|
|
|
|
Build before `collectstatic`. The generated `vite/.vite/manifest.json` and `vite/assets/*` are collected with all other Django static files. Do not use the Vite development server in production.
|
|
|
|
## Reuse in a fresh Django project
|
|
|
|
Copy these files and directories:
|
|
|
|
```text
|
|
vite_integration/
|
|
frontend/src/
|
|
scripts/dev-django.mjs
|
|
vite.config.mjs
|
|
package.json
|
|
.env.vite.example
|
|
```
|
|
|
|
Create `frontend/src/entries/site.js` (or another entry beneath `VITE_ENTRY_DIR`) that imports the page CSS and JavaScript. Then add `vite_integration` to `INSTALLED_APPS`, add the template tag to a base template, configure `STATIC_URL`/`STATIC_ROOT`, install npm packages, and use the development or production commands above. The integration contains no application names, routes, or backend URLs.
|
|
|
|
## Configuration values to customize
|
|
|
|
| Variable/setting | Default | Purpose |
|
|
| --- | --- | --- |
|
|
| `DJANGO_DEV_COMMAND` | `python manage.py runserver <host>:<port>` | Complete backend development command |
|
|
| `DJANGO_HOST`, `DJANGO_PORT` | `127.0.0.1`, `8000` | Default backend bind address |
|
|
| `VITE_HOST`, `VITE_PORT` | `127.0.0.1`, `5173` | Vite bind address and port |
|
|
| `VITE_DEV_SERVER_URL` | `http://127.0.0.1:5173/` | URL Django templates use for HMR |
|
|
| `VITE_DEV_BASE_URL` | `/` | Development-only Vite base path |
|
|
| `VITE_USE_DEV_SERVER` | `false` | Enables HMR tags; set only for development |
|
|
| `VITE_ENTRY_DIR` | `frontend/src/entries` | Directory Vite scans for page entry points |
|
|
| `VITE_ENTRY` | unset | Optional comma-separated explicit entry point list |
|
|
| `VITE_OUT_DIR` | `vite_integration/static/vite` | Build output relative to project root |
|
|
| `VITE_STATIC_PREFIX` | `vite` | Django static namespace for built files |
|
|
| `VITE_BASE_URL` | `/static/vite/` | Public base URL emitted by Vite |
|
|
| `VITE_MANIFEST_PATH` | staticfiles finder | Optional explicit manifest location |
|
|
|
|
Django settings override environment variables with the same names. `VITE_BASE_URL` must equal the public `STATIC_URL` followed by `VITE_STATIC_PREFIX` (for example, `/static/vite/`). A `.env.vite` file is not automatically read by Django; export/source it in the process manager, shell, container, or deployment configuration.
|
|
|
|
## Troubleshooting
|
|
|
|
- **Vite manifest not found:** run `npm run build` before `collectstatic`; check that `VITE_OUT_DIR` ends below a Django app `static/` directory and that its final segment matches `VITE_STATIC_PREFIX`.
|
|
- **Browser cannot reach HMR:** set `VITE_DEV_SERVER_URL` to the browser-reachable Vite address, and use matching `VITE_HOST`/`VITE_PORT`. For containers or remote browsers this is often `0.0.0.0` for the host plus a public hostname for the URL.
|
|
- **A page fails in development:** set `VITE_USE_DEV_SERVER=true` only while `npm run vite` or `npm run dev` is running.
|
|
- **Assets return 404 after deployment:** rerun both the build and `collectstatic`; ensure the web server serves `STATIC_ROOT` at `STATIC_URL`.
|
|
|
|
## Interface translations
|
|
|
|
English text in templates and Python is the source language. Dutch translations live in `locale/nl/LC_MESSAGES/django.po`; the compiled `django.mo` is used at runtime. Logged-in users choose their language at `/settings/`. Visitors use the language switcher in the public navigation, which saves Django's standard language cookie. URLs and stored status or source codes do not change with the language.
|
|
|
|
Update translations after changing user-facing source text:
|
|
|
|
```bash
|
|
python manage.py makemessages -l nl --ignore=node_modules --ignore=staticfiles --ignore='*.orig'
|
|
# Edit locale/nl/LC_MESSAGES/django.po
|
|
python manage.py compilemessages
|
|
```
|
|
|
|
The small amount of JavaScript UI text is translated by Django in `templates/js_translations.html` and read from `window.BOOMCAST_I18N`. After changing JavaScript, run `npm run build` and `python manage.py collectstatic --noinput` for production. Classifier class names, API keys, sensor tokens, H3 values and stored source/status values remain language-neutral.
|
|
|
|
## Browser Processing Beta
|
|
|
|
The administrator setting `browser_processing_beta_enabled` is off by default.
|
|
When enabled, the upload form shows **Process recording in this browser (Beta)**,
|
|
which also starts off. With the user toggle off, ordinary audio uses the
|
|
existing server upload and classifier. With it on, selected audio is checked
|
|
locally and selected video is converted to 16 kHz mono WAV before the local
|
|
check. Files the user submits still run through the server classifier.
|
|
Switching back to server mode cancels browser work and clears the local gate.
|
|
The server upload endpoint currently accepts audio, so a video selected in
|
|
server mode requires an audio file or browser mode.
|
|
|
|
Browser assets are loaded only after the user enables the toggle and selects a
|
|
file. Regenerate the self-hosted model using [the YAMNet build guide](scripts/BROWSER_YAMNET.md),
|
|
then run `npm run build` and `python manage.py collectstatic --noinput`.
|
|
# Pending event notifications
|
|
|
|
Users can test and enable an ntfy topic in Settings. New Pending events are
|
|
counted by source (manual or sensor) in one-minute batches per enabled user.
|
|
Run `python manage.py send_pending_notifications` once per minute with the
|
|
application's Python environment and working directory. For example, a cron
|
|
entry can use `* * * * * cd /path/to/django && /path/to/python manage.py send_pending_notifications`.
|
|
It sends completed minute batches,
|
|
then removes them; failed deliveries remain queued for the next run.
|
|
|
|
For a systemd user timer on the laptop, install the units in
|
|
[`deploy/systemd/`](deploy/systemd/) and start the timer:
|
|
|
|
```sh
|
|
cd /home/jorenmartijn/python/django
|
|
/usr/bin/python3 -m venv /home/jorenmartijn/python/.venv-notifications
|
|
/home/jorenmartijn/python/.venv-notifications/bin/python -m pip install -r requirements.txt
|
|
/home/jorenmartijn/python/.venv-notifications/bin/python manage.py check
|
|
mkdir -p ~/.config/systemd/user
|
|
cp deploy/systemd/send-pending-notifications.service deploy/systemd/send-pending-notifications.timer ~/.config/systemd/user/
|
|
systemctl --user daemon-reload
|
|
systemctl --user enable --now send-pending-notifications.timer
|
|
systemctl --user list-timers send-pending-notifications.timer
|
|
```
|
|
|
|
The service runs `/home/jorenmartijn/python/.venv-notifications/bin/python` with this
|
|
project as its working directory. To keep the user timer running after logout,
|
|
run `sudo loginctl enable-linger jorenmartijn` once on the laptop. Check a run
|
|
with `journalctl --user -u send-pending-notifications.service -n 30`.
|
|
|
|
### Burst Listening watchdog
|
|
|
|
Run one shared `watch_burst_sessions` process alongside Django so a suspended PWA is
|
|
marked heartbeat-lost independently of browser JavaScript. A systemd user service
|
|
is provided at `deploy/systemd/watch-burst-sessions.service`; enable it for the
|
|
same user and Python environment as Django. `--once` is available for tests and
|
|
manual checks. A one-minute cron job cannot meet the 15-second timeout target.
|
|
For a user service: copy the unit to `~/.config/systemd/user/`, run
|
|
`systemctl --user daemon-reload`, then
|
|
`systemctl --user enable --now watch-burst-sessions.service`.
|