Example Applications¶
16 production-ready example apps showcasing every major HyperDjango feature. Each is self-contained with app.py, seed.py, and E2E tests.
Quick Start (any app)¶
cd examples/<app_name>
uv run hyper setup --app app:app --drop --seed seed:run
uv run hyper start --app app:app --port 8000
App Catalog¶
Beginner¶
| App | Directory | Showcases | Port |
|---|---|---|---|
| Hello | hello/ |
Minimal starter — one route, one response | 8000 |
| Notes API | notes_api/ |
Session auth, F expression updates, cursor pagination, HyperAdmin | 8700 |
| Forms Demo | forms_demo/ |
Form validation, ModelForm, cross-field clean, file uploads | 8600 |
| REST API | rest_api/ |
CRUD, opaque IDs, session + API key auth, OpenAPI/Swagger | 8100 |
Intermediate¶
| App | Directory | Showcases | Port |
|---|---|---|---|
| Full Stack | full_stack/ |
Templates, forms, admin panel, project/task CRUD | 8200 |
| Bookstore API | bookstore_api/ |
ViewSets, serializers, CursorPagination, ETag, nested routers, RBAC | 8300 |
| Content Hub | content_hub/ |
Q objects, OneToOneField, STI, custom actions, RBAC roles | 8400 |
| WebSocket Chat | websocket_chat/ |
Zig RFC 6455, rooms, presence, typing indicators, Channel pub/sub | 8500 |
| Task Queue | task_queue/ |
@app.task, priorities, retry, DLQ, TaskGroup, cron scheduling | 8800 |
| Blog Platform | blog_platform/ |
XML sitemaps, RSS/Atom feeds, i18n (LocaleMiddleware), multi-language | 8750 |
| CMS Lite | cms_lite/ |
Flat pages (FlatPageRegistry), URL redirects (RedirectRegistry) | 8760 |
| Metering API | metering_api/ |
Usage metering (MeterEngine), quotas, IETF RateLimit headers | 8770 |
Advanced¶
| App | Directory | Showcases | Port |
|---|---|---|---|
| HyperNews | hypernews/ |
Voting system, eigenvector ranking, StatusTimeline, keyset pagination | 8900 |
| HyperAI | hyperai/ |
LLM chat, SSE streaming, tiered rate limits, SignedAPIKeyMixin | 9000 |
| HyperTicket | hyperticket/ |
Multi-tenant SaaS, 27+ models, guard RBAC, SLA tracking, workflows | 9100 |
| Multi-Tenant | multi_tenant/ |
TenantMixin, enum fields, org hierarchy, tenant isolation | 9200 |
| Semantic Search | semantic_search/ |
pgvector, HNSW cosine similarity, OpenAI-compatible embeddings API | 9300 |
Infrastructure¶
| App | Directory | Showcases | Port |
|---|---|---|---|
| Deployment | deployment/ |
systemd, nginx, env template, health probes, production config | 9400 |
| Benchmark | benchmark_app/ |
EXPLAIN ANALYZE performance testing, regression detection | 9500 |
Features by App¶
| Feature | Apps |
|---|---|
| HyperAdmin | All except hello, benchmark, deployment |
| Swagger UI | bookstore_api, rest_api, task_queue, multi_tenant, content_hub, hyperai, notes_api, forms_demo, semantic_search, websocket_chat, full_stack, blog_platform, cms_lite, metering_api |
| SessionAuth | All auth-enabled apps (17/19) |
| RBAC Groups | bookstore_api, content_hub, full_stack, hypernews, hyperticket |
| XML Sitemaps | blog_platform |
| RSS/Atom Feeds | blog_platform |
| i18n | blog_platform |
| Flat Pages | cms_lite |
| URL Redirects | cms_lite |
| Usage Metering | metering_api |
| IETF Rate Limit Headers | metering_api |
| Meta.indexes | hypernews (36 indexes), hyperticket (46 indexes) |
| StatusTimeline | hypernews (ban/mute/staff), hyperticket (lock/mute/agent), multi_tenant (org suspend) |
| Telemetry | bookstore_api (metrics + spans), hyperai (span tracing) |
| WebSocket | websocket_chat (native Zig RFC 6455) |
| CursorPagination | bookstore_api, notes_api, rest_api, content_hub |
| Field Permissions | bookstore_api (via field_permissions_model) |
Seed Credentials — Dynamic by Default¶
No example app ships with hardcoded passwords. Every seed user (and the HyperAdmin panel user) gets its password from the settings system at seed time, falling back to a randomly-generated value that is printed to the startup log.
Resolution order for app users (via seed_password("username")):
HYPER_SEED_PASSWORD_<USERNAME>setting (per-user override, e.g.HYPER_SEED_PASSWORD_ALICE)HYPER_SEED_PASSWORDsetting (global fallback for all seed users)secrets.token_urlsafe(16)— random, printed to the log so the operator can record it
Resolution order for the HyperAdmin panel user (via ensure_admin_user()):
- Explicit
password=argument HYPER_ADMIN_PASSWORDsettingsecrets.token_urlsafe(16)— random, printed to the log
Running an example with a known password¶
HYPER_SEED_PASSWORD=mydevpw HYPER_ADMIN_PASSWORD=mydevpw \
uv run hyper setup --app examples.bookstore_api.app:app --drop \
--seed examples.bookstore_api.seed:run
HYPER_SEED_PASSWORD=mydevpw HYPER_ADMIN_PASSWORD=mydevpw \
uv run hyper run --app examples.bookstore_api.app:app
Letting the seed pick random passwords¶
uv run hyper setup --app examples.bookstore_api.app:app --drop \
--seed examples.bookstore_api.seed:run
# Look for "Generated seed password for 'admin': <token>" in the startup log.
E2E tests set both env vars in scripts/test_runner.py so every test run gets a
deterministic, isolated password (SEED_PASSWORD / ADMIN_PASSWORD constants
in e2e_helper.py).