REEF

RFC Editor Engagement Features

REEF (RFC Editor Engagement Features) is the IETF self-hosted survey and engagement service, part of the RFC Modernization Phase 2 program alongside Red (the public RFC website). It hosts SurveyJS on our own infrastructure and exposes engagement APIs that Red consumes.

What Reef does

• Surveys, full stack:
  • A Django-hosted survey builder (SurveyJS Creator) and analytics dashboard (SurveyJS Analytics), under /manage/, for staff.
  • A themed Nuxt survey runner (/s?slug=<slug>) where visitors fill out surveys.
  • An API that lists open surveys, serves definitions, and stores responses. Red queries the open-survey list and links out to the runner.
• Ratings, popularity, and subscriptions: APIs consumed by Red (their UI lives in Red). Reef owns storage and aggregation, and sends subscription emails.

Surveys are built end to end; ratings, popularity, and subscriptions are scaffolded (models and endpoints in place, to be completed next). See plan.md for the full design.

Architecture

Django 5 and Django REST Framework with PostgreSQL back the service. An NGINX front proxy serves one origin: the Django site and API, and the Nuxt runner. Authentication is OIDC against the IETF Authentik instance at https://account.ietf.org/. The API contract is generated by drf-spectacular into reef_api.yaml, which both the Nuxt client (via openapi-typescript) and Red consume.

Browser -> NGINX :8088 -> Django + DRF :8001 -> PostgreSQL
                       -> Nuxt runner :3001
Red -> /api/reef/... (bearer / anonymous) -> Django + DRF
Red -> precomputed JSON <- blob store <- manage.py precompute

The precomputer renders the public API responses ahead of time and writes them to a blob store, so that a reader is served a file rather than a query that aggregates every rating, subscription and set entry. It is one command, manage.py precompute, meant to be run on a schedule; with no bucket configured it writes to ./precomputed and needs no object storage.

Quick start

Requires Docker. Two options:

• VS Code Dev Containers: open the repository in the container. Initialization installs dependencies, runs migrations, vendors the SurveyJS bundles, and starts the Django and Nuxt servers behind NGINX.
• Generic Docker: run docker/run, which builds the containers and launches a tmux session with the servers.

The app image builds FROM ghcr.io/ietf-tools/reef-app-base. Until CI publishes it, build it locally first:

docker build -f docker/base.Dockerfile -t ghcr.io/ietf-tools/reef-app-base:latest .

Then browse:

• http://localhost:8088/ - the Nuxt survey runner
• http://localhost:8088/manage/surveys/ - the survey builder and analytics (login)
• http://localhost:8088/admin/ - Django admin (break-glass superuser)
• http://localhost:8088/api/reef/schema/swagger-ui/ - API docs
• http://localhost:8025/ - mailpit (captured email)
• http://localhost:8088/pgadmin/ - pgAdmin

Configuration

Copy .env.example to .env and fill in the Authentik client credentials and (for production) the SurveyJS license key. See docs/development.md for the full list of settings and the Authentik application setup, including the redirect URIs to register.

Tests and linting

./manage.py test          # Django tests
ruff check .              # lint
ruff format --check .     # format check
REEF_DEPLOYMENT_MODE=build ./manage.py spectacular \
  --file reef_api.yaml --validate            # API schema
cd client && npm run typecheck                            # client types

Deployment

Production images are built from dev/build/ (backend, frontend, statics) and published to ghcr.io by the GitHub Actions in .github/workflows/. Deployment uses Kustomize: k8s/base with k8s/overlays/staging and k8s/overlays/production.

Repository layout

• reef/ - Django project (settings package, celery, urls)
• reefauth/ - custom user and OIDC (login backend plus bearer resource-server auth)
• surveys/ - survey models, API, and the /manage/ builder and analytics
• ratings/, popularity/, subscriptions/ - engagement API apps
• templates/ - Django templates, currently the notification email bodies
• client/ - Nuxt survey runner
• vendor/ - self-hosted SurveyJS bundles
• docker/ - dev container and compose tooling
• dev/build/ - production image builds
• k8s/ - Kustomize manifests