Modern, extensible and privacy‑aware Django backend for managing hackathon applications, teams, logistics and stats.
HackAssistant is a modern re‑implementation of the original HackAssistant/registration and is heavily based on the upstream HackAssistant/hackassistant project. Full credit to the HackAssistant maintainers and contributors. This fork focuses on:
- Maintainability (modular apps, mixins, documented utilities)
- Privacy & compliance (age anonymization, explicit consents)
- Extensibility (pluggable apps: friends/teams, messages, meals, stats, tables)
- Operational visibility (stats & tables, export formats, cron jobs)
- Security hardening (brute force protection, admin honeypot, CSP, password history, reCAPTCHA)
This repository powers the official registration and attendee operations platform for HackMTY and includes event‑specific tweaks.
Highlights adapted for HackMTY:
- Consent ordering tuned for local policies first
- Age privacy layer (integer age → synthetic birth_date)
- Mandatory phone number & stricter validations for on‑site logistics
- Centralized Level of Study synced to profile
- Admissions workflow with Invite, Waitlist and Reject actions (distinct statuses and emails)
- Friends (teams) with capacity and Devpost project link capture (visible starting on the event day)
- Event banners and date‑gated disclaimers (e.g., no re‑entry window)
Accounts & Security
- Email registration & login (django‑allauth)
- Email verification & password reset
- Password reuse prevention (history) + composition validators
- Brute force mitigation with django‑axes (IP cool‑off)
- Admin honeypot and CSP defaults
Applications
- Configurable application types (Hacker, Volunteer, Mentor, Sponsor)
- Hidden types with token-gated apply links for private programs (e.g., Sponsor). Rotate tokens from admin.
- Extra dynamic fields stored as JSON (
form_data) + file uploads with overwrite - Promotional codes, custom consents, MLH‑style policy capture
- Invite / Waitlist / Reject organizer actions and tailored emails
Teams (Friends)
- Join by code, leave, capacity limit (configurable)
- Team closed when any member is invited/confirmed/attended
- Full teams can attach a Devpost URL (editing enabled for team members; card visible from the event start date)
Organizer tooling
- Review list and actions, stats with filters, exportable tables
- Admin panel for teams: list by code, counts, filters, CSV export, deep links
Event ops
- Messages and meals sub‑apps (optional)
- Cron jobs for invitation expiry and housekeeping
UI/UX
- Bootstrap 5 forms and layout helpers
- Light/Dark themes (both available)
app/ Global project (settings, urls, templates, middlewares, logging, theme)
application/ Application model & type‑specific forms (Hacker, Mentor, etc.)
user/ Custom user model, forms, profile logic, choices
review/ Review workflows (organizer tools)
stats/ Statistics generation & filtering
tables/ Table utilities & views
friends/ Teaming (join/leave, capacity, Devpost)
event/ Event domain (messages, meals sub‑apps)
files/ Uploaded resume & file storage
staticfiles/ Collected & hashed static assets (production)
production/ Production docker-compose & scripts
- Django 4.2, Python 3.9/3.10
- Auth: django‑allauth; JWT/OIDC provider mode available (django‑jwt‑oidc)
- Security: django‑axes, admin‑honeypot, CSP, password validators, reCAPTCHA
- UI: Bootstrap 5 (django‑bootstrap5)
- Tables/Export: django‑tables2 + tablib formats
- Email: AnyMail (Mandrill) with file‑based fallback in DEBUG
- Scheduling: django‑crontab
- Assets: django‑compressor, libsass, ManifestStaticFilesStorage
Prerequisites: Docker, Docker Compose.
git clone https://github.com/HackAssistant/hackassistant.git
cd hackassistant
./install.sh # sets up virtualenv, installs deps, applies migrations (ok to run with docker)
docker-compose up # launches dev server at http://localhost:8000Common dev commands:
docker-compose run python manage.py makemigrations
docker-compose run python manage.py migrate
docker-compose run python manage.py createadmin
docker-compose run python -m pip install <library>Static & compress (optional locally):
docker-compose run python manage.py collectstatic --noinput
docker-compose run python manage.py compress --forcePrerequisites: Python 3.9+.
git clone https://github.com/HackAssistant/hackassistant.git
cd hackassistant
python -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
python manage.py migrate
python manage.py createadmin # creates initial organizer admin
python manage.py runserver 0.0.0.0:8000| Variable | Purpose | Default / Notes |
|---|---|---|
| SECRET_KEY | Django secret key | required |
| PROD_MODE | Toggle production security flags | False |
| ALLOWED_HOSTS | Comma separated hosts | empty (+ localhost in DEBUG) |
| DB_ENGINE | sqlite3 / postgresql / mysql / oracle | sqlite3 |
| DB_NAME / DB_USER / DB_PASSWORD / DB_HOST / DB_PORT | DB credentials (non‑sqlite) | — |
| GOOGLE_RECAPTCHA_SITE_KEY / GOOGLE_RECAPTCHA_SECRET_KEY | reCAPTCHA keys | optional |
| AXES_FAILURE_LIMIT | Brute force attempt limit | default 6 here |
| AXES_ENABLED | Enable django‑axes | not DEBUG |
| ADMIN_URL | Secret admin path | secret/ |
| OIDC_DISCOVERY_ENDPOINT | JWT/OIDC provider discovery | local default |
| HACKATHON_START_DATE / HACKATHON_END_DATE | dd/mm/YYYY | drives event gating (e.g., disclaimers, Devpost card) |
See app/settings.py and app/hackathon_variables.py for more.
User (user.User)
- Email is the primary credential; extended demographics; synthetic birth_date from age input.
Application (application.Application)
- One per type and edition; extra fields inside
form_dataJSON. Files stored under<edition>/<type>/<field>/<name>_<uuid>.<ext>. - Organizer actions support Invite, Waitlist, Reject with dedicated emails.
- Cancelling a Hacker application removes the user from their team and frees a spot.
Teams (Friends)
- Join by code; leave any time; team closes if any member is invited/confirmed/attended.
- Capacity enforced via
FRIENDS_MAX_CAPACITY. - When full, a Devpost URL card appears starting on the event day for members to add/edit the project link.
Stats & Tables
- Aggregated metrics and exportable tables for operational insight.
- Axes login throttling (5‑minute cool‑off) and configurable attempt limit
- Admin honeypot, CSP headers, secure cookies (when PROD_MODE=true)
- Password history and composition validators
- reCAPTCHA protection
Typical jobs include invitation expiry and housekeeping. Register on boot via python manage.py crontab add.
List / remove:
python manage.py crontab show
python manage.py crontab remove- Prefer a reverse proxy (nginx/traefik) in front of gunicorn.
- Recommended 5 MB upload limit and friendly 413 redirect:
client_max_body_size 5m;
error_page 413 =302 /upload-too-large/;- Example production compose in
production/docker-compose.yml.
| Symptom | Likely cause | Fix |
|---|---|---|
| 413 on upload | Proxy limit | Set client_max_body_size and friendly redirect |
| Missing static | Not collected | manage.py collectstatic |
| 403 on /application for organizers | Intentional to keep reviewer UI clean | Use reviewer pages or adjust ApplicationHome.dispatch |
| Hidden Sponsor link returns 404 | Missing/invalid token | Use the share link shown in Admin > Application type > Sponsor, or rotate token via action |
- Fork and branch (
feature/<short>) - Keep patches focused; update docs
- Run linters and Django checks
- Open PR with context and screenshots (for UI)
Distributed under the project LICENSE. For security issues, follow SECURITY.md and avoid public issues.
# Dev up (docker)
docker-compose up
# Migrations
docker-compose run python manage.py makemigrations
docker-compose run python manage.py migrate
# Create admin
docker-compose run python manage.py createadmin
# Static & compress
docker-compose run python manage.py collectstatic --noinput
docker-compose run python manage.py compress --force
# Cron jobs
docker-compose run python manage.py crontab showHappy hacking! 🚀
- This project is built on the shoulders of HackAssistant/hackassistant and the original HackAssistant/registration. Huge thanks to all maintainers and contributors of the upstream projects.