Skip to main content
This guide gets the SMS project running for local development.

​
Prerequisites

  • Python 3.12+
  • PostgreSQL 15+ (Docker recommended)
  • Redis (optional for local dev; recommended for Celery and caching in production)
  • Git

​
Step-by-step installation

​
Step 1: Clone the repository

git clone <repository-url>
cd sms

​
Step 2: PostgreSQL (Docker)

docker run --name postgres-dev \
  -e POSTGRES_DB=devdb \
  -e POSTGRES_USER=devuser \
  -e POSTGRES_PASSWORD=devpass \
  -p 5432:5432 \
  -d postgres:15

​
Step 3: Virtual environment and dependencies

python -m venv venv
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

pip install -r requirements.txt

​
Step 4: Environment variables

Copy the example env file and edit as needed: 
cp .env.example .env.dev
Important: Set ENVIRONMENT so the app uses .env.dev (e.g. leave default or set ENVIRONMENT=development). Ensure DATABASE_URL matches your PostgreSQL setup, for example:
  • postgres://devuser:devpass@localhost:5432/devdb
Other common variables:
VariablePurpose
SECRET_KEYDjango secret (required)
DEBUGSet to True in dev
ALLOWED_HOSTSComma-separated hosts
REDIS_URLOptional; used for cache and Celery
CACHE_BACKENDredis or dummy (dev)

​
Step 5: Migrations (django-tenants)

Run shared (public) migrations first, then tenant schemas: 
python manage.py makemigrations authentication
python manage.py makemigrations clients
python manage.py makemigrations core
python manage.py makemigrations chatbot
python manage.py makemigrations

python manage.py migrate_schemas --shared
python manage.py migrate_schemas

​
Step 6: Create a tenant (school)

The app uses django-tenants: each school is a Client with a Domain. You can:
  • Create a tenant via Django admin (after creating a superuser with python manage.py createsuperuser), or
  • Use the system API once the first platform user exists: POST /api/v1/system/schools/ (and add a Domain), or
  • Use any custom management command your project provides (e.g. create_tenant if present).
Ensure at least one Domain points to your dev host (e.g. localhost or school1.localhost) so requests resolve to the correct schema.

​
Step 7: Run the server

python manage.py runserver
  • API: http://localhost:8000
  • Swagger UI: http://localhost:8000/api/docs/
  • ReDoc: http://localhost:8000/api/redoc/
  • Admin: http://localhost:8000/admin/ (after createsuperuser)
For school endpoints, send requests to the tenant domain (e.g. the host you configured for that Client). For system endpoints, use the main/public domain. You can also use the X-Schema-Name header (superadmin) to target a schema without subdomains.

​
Optional: Celery and Redis

For chatbot background tasks and report generation:
  1. Start Redis (e.g. docker run -d -p 6379:6379 redis:7).
  2. Set REDIS_URL and CACHE_BACKEND=redis in .env.dev.
  3. Run a worker: celery -A sms worker -l info (and optionally beat for scheduled tasks).