Getting started for developers

Spin up the full GreekManage stack on your machine in under 10 minutes.

Prerequisites

• Docker Desktop (or Docker Engine + Compose v2)
• Git
• Node 20+ and Python 3.13+ if you want to run the frontend or backend outside Docker (optional — Compose handles it)
• ~10 GB of free disk for images, database, and MinIO storage

Clone

git clone https://github.com/amankundlas/greekmanage.git
cd greekmanage

Configure environment

cp .env.example .env

Edit .env and set the required values:

Variable	How to generate / what to put
POSTGRES_PASSWORD	Strong random — openssl rand -hex 32
DJANGO_SECRET_KEY	python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
ENCRYPTION_KEY	python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
ANTHROPIC_API_KEY	Your Anthropic key (only required if you want the AI chatbot to work)

The other variables in .env.example have safe defaults for local dev.

Start the stack

docker compose up

This launches:

Service	Port	Purpose
frontend	3000	Vite dev server (React + TypeScript)
backend	8000	Django + Daphne (ASGI)
db	5432	PostgreSQL 17 + pgvector
redis	6379	Celery broker + Channels layer
minio	9000 / 9001	S3-compatible object storage + console
celery	–	Worker (concurrency=2)
celery-beat	–	Periodic task scheduler
celery-backups	–	Isolated worker for the backups queue

First boot takes a few minutes (image pulls, migrations, MinIO bucket init). Subsequent starts are seconds.

Run migrations + seed data

In a second terminal:

docker compose exec backend python manage.py migrate
docker compose exec backend python manage.py loaddata seed_data
docker compose exec backend python manage.py createsuperuser

The seed_data fixture creates a sample org, region, chapter, and members so the app isn't empty on first sign-in.

Open the app

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000/api/
• API schema (OpenAPI): http://localhost:8000/api/schema/
• MinIO console: http://localhost:9001 (credentials in docker-compose.yml)

Sign in with the superuser you just created.

Common dev tasks

Run the test suite

Backend:

docker compose exec backend pytest

Frontend:

docker compose exec frontend npm test

E2E (Playwright):

cd e2e
npm install
npm run test:smoke    # quick gate
npm test              # full suite

→ Testing guide

Make a backend code change

The backend container mounts ./backend as a volume. Edits hot-reload via Django's auto-reloader. No restart needed.

For settings changes or new dependencies:

docker compose restart backend

Make a frontend code change

Vite hot-reloads in the browser as you save. For new dependencies:

docker compose exec frontend npm install <package>
docker compose restart frontend

Run a Django management command

docker compose exec backend python manage.py <command>

Useful built-ins:

• python manage.py shell — interactive Django shell
• python manage.py dbshell — psql into the dev DB
• python manage.py spectacular --file openapi.yaml — regenerate the API schema
• python manage.py check — run system checks

Reset the database

docker compose down -v        # removes volumes including postgres data
docker compose up
docker compose exec backend python manage.py migrate
docker compose exec backend python manage.py loaddata seed_data

Inspect Celery tasks

docker compose logs -f celery celery-beat

To trigger a periodic task immediately:

docker compose exec backend python manage.py shell
>>> from apps.compliance.tasks import calculate_compliance_scores
>>> calculate_compliance_scores.delay()

Editor setup

VS Code

Recommended extensions:

• ms-python.python + ms-python.vscode-pylance
• ms-azuretools.vscode-docker
• dbaeumer.vscode-eslint
• esbenp.prettier-vscode
• bradlc.vscode-tailwindcss

Workspace settings to set Python interpreter to the container:

{
  "python.defaultInterpreterPath": "/usr/local/bin/python"
}

Pre-commit hooks

cd .husky && npm install

Husky runs lint + type-check on every commit. Failures block the commit.

Troubleshooting

Symptom	Likely cause	Fix
db container fails health check	Port 5432 in use	lsof -i:5432, kill the offender, or change POSTGRES_PORT
backend exits with ENCRYPTION_KEY error	Empty key	Generate one (see above)
Frontend "Network error"	Backend not ready	Wait for backend health check; or docker compose logs backend
pytest collects 0 tests	Wrong working dir	Run from backend/ or cd backend && pytest
MinIO 403 on file uploads	Bucket policy not set	docker compose restart minio-init
Hot-reload not working	Saved outside the mounted volume	Make sure you're editing files in ./backend or ./frontend

What's next

• Tech stack — full list of libraries
• Architecture overview — how it all fits together
• Contributing — branch / PR workflow
• API reference — every endpoint