django-snapnote

Let your users report a problem from any page: a floating button captures the tab, lets them draw on it and creates a ticket you can review in the admin or in built-in views.

Requires only Django (4.2–5.2) and Pillow. No DRF, no Node, no build step for you. The widget is a self-contained bundle rendered in a Shadow DOM, so your CSS and ours don't interfere.

Install

pip install django-snapnote

# settings.py
INSTALLED_APPS += ["snapnote"]          # needs django.contrib.auth and staticfiles

# urls.py
path("snapnote/", include("snapnote.urls")),   # report endpoint + management views

{# in your base template (the view needs the request context processor) #}
{% load snapnote_tags %}
{% snapnote_button %}

Then python manage.py migrate. Uploaded images use your MEDIA_ROOT/storage.

Settings

Customise the look by overriding CSS variables on #snapnote-root (--snapnote-accent, --snapnote-accent-text, --snapnote-z-index, --snapnote-font).

Permissions

Reporting follows SNAPNOTE_CAN_REPORT. Managing uses the model permissions snapnote.view_ticket, change_ticket and delete_ticket (superusers have them all). Anonymous users are redirected to LOGIN_URL; authenticated users without permission get 403.

Notifiers

The signal snapnote.signals.ticket_created(sender, ticket, request_url) is sent after commit. A notifier is any callable; a failing one is logged and never breaks the report:

# myproject/notifiers.py — Slack recipe
import requests
def slack(ticket, url):
    requests.post(settings.SLACK_WEBHOOK, json={"text": f"New ticket: {ticket.title} {url}"}, timeout=5)

SNAPNOTE_NOTIFIERS = ["snapnote.notifiers.email", "myproject.notifiers.slack"]

Jira notifier

Built in, opt-in and dependency-free (stdlib only). It creates a Jira Cloud issue per ticket, with the page URL, a link to the Snapnote ticket and, optionally, the screenshot and annotations attached:

SNAPNOTE_NOTIFIERS = ["snapnote.notifiers.email", "snapnote.notifiers.jira_issue"]
SNAPNOTE_JIRA_URL = "https://yourcompany.atlassian.net"
SNAPNOTE_JIRA_EMAIL = "bot@yourcompany.com"
SNAPNOTE_JIRA_API_TOKEN = os.environ["JIRA_API_TOKEN"]   # https://id.atlassian.com/manage-profile/security/api-tokens
SNAPNOTE_JIRA_PROJECT = "APP"                            # project key
# optional: SNAPNOTE_JIRA_ISSUE_TYPE = "Bug", SNAPNOTE_JIRA_LABELS = ["snapnote"],
#           SNAPNOTE_JIRA_ATTACH_IMAGES = True, SNAPNOTE_JIRA_TIMEOUT = 10

manage.py check warns (snapnote.W002) if a required setting is missing. Use a dedicated Jira account with access only to that project. Notifiers run synchronously after commit with the timeout above; for heavy use, wrap it in your own task queue. Screenshots may contain sensitive data: they are attached to the issue, so keep SNAPNOTE_JIRA_ATTACH_IMAGES = False if the Jira project is broader than who may see them.

Security and deployment notes

• Screenshots can contain sensitive data. Serve MEDIA_ROOT only to authenticated staff (or use a private storage); do not expose it publicly. Purge old reports with python manage.py snapnote_purge --older-than 90 (--dry-run to preview).
• Permissions-Policy: the browser needs display-capture=(self). With display-capture=() (also sent by some proxies) capture never works and users get the upload fallback.
• CSP: allow img-src blob: data: and style-src 'unsafe-inline' (the Shadow DOM stylesheet is inline) and script-src for the static bundle.
• Uploads are validated (PNG/JPEG/WebP only, no SVG), size/dimension limited and re-encoded with Pillow.
• page_url must be http(s) and is never rendered as a clickable link otherwise.
• The report endpoint uses Django's CSRF protection; the template tag sets the cookie.
• Capture uses getDisplayMedia (desktop browsers). On mobile the user attaches an image.

Development

pip install -e . pytest pytest-django
pytest                      # SQLite; SNAPNOTE_TEST_DB=postgres for PostgreSQL
cd frontend && npm ci && npm run build   # writes src/snapnote/static/snapnote/snapnote.js
npm test && npm run e2e

The built snapnote.js is committed/packaged so installing the wheel never needs Node.