This guide walks through setting up LicenseHubK12 for the first time, from prerequisites to your first login. LicenseHubK12 is a self-hosted Flask application, so you’ll need a server (or local machine) to run it on.
Prerequisites
Before you begin, make sure you have:
- Python 3.13+
- Git
- uv — the Python package manager LicenseHubK12 uses for dependency management
- MySQL or MariaDB — for production use (local development runs on SQLite, no extra setup required)
1. Clone the repository
git clone https://github.com/victorhugo81/licensehubk12.git
cd licensehubk12
2. Create a virtual environment and install dependencies
uv sync
This installs Flask, SQLAlchemy, Flask-Login, Flask-WTF, Flask-Migrate, and every other dependency pinned in the project.
3. Configure your environment
Copy the example environment file and fill in your own values:
cp .env.example .env
For local testing you can leave the database on SQLite. For production, set APP_ENV=production, a real SECRET_KEY, and your MySQL/MariaDB connection string.
4. Set up the database
Run the project’s Flask-Migrate setup to create the schema. Check the repository README for the exact current command, as it may include separate flask db upgrade and seed steps.
5. Run it
For local testing, start the Flask development server directly. For production, run behind gunicorn with a reverse proxy (nginx or similar) in front of it, and terminate TLS at the proxy.
gunicorn -w 4 -b 0.0.0.0:8000 wsgi:app
If you run more than one gunicorn worker, add Redis for shared rate-limit storage. If you enable the optional APScheduler notification jobs, keep that to a single worker to avoid duplicate notification runs.
6. Log in and configure your district
- Log in with the administrator account created during setup.
- Add your schools, vendors, and contracts before importing licenses.
- Bulk-load license data with the two-phase CSV import — it validates the file and shows you a preview before anything is written to the database.
- Bulk-create user accounts via CSV or a scheduled FTP/FTPS import, and assign each person one of the five role tiers.
- Configure expiration, renewal, utilization, and new-license notifications — each is independently toggleable.
Security notes
LicenseHubK12 ships with several protections enabled by default:
- PBKDF2/scrypt password hashing
- Global CSRF protection and route-level role-based access control
- Rate-limited login attempts with temporary account lockouts; password changes rotate session identifiers
- Security headers on every response (CSP with per-request nonces, HSTS, X-Frame-Options)
- Formula-injection-safe CSV exports and ORM-only database access (no raw SQL interpolation)
Next steps
- Read the product overview for a full feature breakdown.
- See the bulk import guide for the
users.csvandsites.csvformats. - Invite your IT and curriculum teams and assign roles.
- Star and watch the GitHub repository for updates.