Developer Setup

Run HolidayOps on your own machine.

Requirements

• uv (installs Python 3.12 for you)
• Node.js 22.22 or newer
• Docker Desktop, running (MySQL 8 and Redis run in containers)

First run

git clone https://github.com/ahmershahdev/holidayops.git
cd holidayops
cp .env.example .env    # set DJANGO_SECRET_KEY, FIELD_ENCRYPTION_KEYS, MySQL passwords, DEMO_PASSWORD
npm install             # root tools
npm run setup           # frontend and Python packages
npm run dev             # MySQL and Redis in Docker; Django :8000, Vite :5173, Celery worker and Beat
npm run seed            # optional: demo user, organization and calendar

Open http://localhost:5173. API docs: http://localhost:5173/api/v1/docs/. The demo user is demo@holidayops.test with the password you set in DEMO_PASSWORD.

Make a FIELD_ENCRYPTION_KEYS value with:

cd backend && uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Without email keys, emails (including sign-up codes) are printed in the api and worker terminal output. Every optional service is described in Configuration.

Other ways to run it

Command	What
docker compose up -d	everything in containers
docker compose -f docker-compose.prod.yml up --build	the production image on http://localhost:8080

Checks before a pull request

CI runs these; run them first.

npm test                                  # pytest (needs MySQL) and Vitest
cd backend
uv run ruff check . && uv run ruff format --check . && uv run mypy .
uv run pytest tests/core --cov=apps/core --cov-branch --cov-fail-under=100
uv run python manage.py spectacular --file schema.yml --validate   # after API changes
cd ../frontend
npm run gen:api                           # after API changes
npm run lint && npm run typecheck
cd .. && npm run messages                 # after template or gettext changes

Good to know

• Tests use MySQL, never SQLite. Run one test session at a time: parallel runs share the test database.
• Windows has no GNU gettext; npm run messages runs inside the backend container.
• Public pages are cached in development too. Touch a .py file or add a throwaway query string to see a template change.
• After dependency changes, a blank page with "Invalid hook call" means you should delete frontend/node_modules/.vite.

More: Troubleshooting and the "Gotchas" list in docs/status.md.