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/.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/.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