Skip to main content
This guide walks you through running the project from scratch after cloning the repository. For deeper architecture and troubleshooting, see the repo root README.md or the rest of this documentation.

​
Prerequisites

  • Docker & Docker Compose — The main stack (web, Celery, Redis, PostgreSQL, admin portal, docs) runs in containers. Install Docker and Docker Compose.
  • Git — To clone the repository.
  • Optional: Mintlify CLI (Node.js v20.17+) — To run the docs locally: from the docs/ directory run mint dev (preview at http://localhost:3000). Production docs are served by the docs Docker service.

​
1. Clone the repository

git clone <repository-url>
cd Panchang-Project
Replace <repository-url> with your repo URL.

​
2. Environment variables

Create a .env file in the project root. The application expects at least the following:
VariablePurpose
DATABASE_URLPostgreSQL connection string (e.g. postgresql+psycopg2://user:password@db:5432/panchang_db for Docker; use host localhost if connecting from host)
CELERY_BROKER_URLRedis URL for Celery (e.g. redis://redis:6379/0)
CELERY_RESULT_BACKENDRedis URL for Celery results (e.g. redis://redis:6379/0)
OPENCAGE_API_KEYOpenCage API key for reverse geocoding (required for location → timezone/city)
WHATSAPP_PHONE_NUMBER_IDWhatsApp Business API phone number ID
WHATSAPP_ACCESS_TOKENWhatsApp Business API access token
SECRET_KEYFlask secret key (used by the admin portal)
ENVdevelopment (default) or production. In development, plain text and location-request messages are mocked (not sent); template messages still call the WhatsApp API. Use production when testing end-to-end with ngrok and the Meta webhook.
Example .env (Docker Compose): 
DATABASE_URL=postgresql+psycopg2://panchang_user:password@db:5432/panchang_db
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0
OPENCAGE_API_KEY=your_opencage_api_key
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_ACCESS_TOKEN=your_access_token
SECRET_KEY=your_flask_secret_key
# ENV=development   # optional; unset or development = mock text/location
# ENV=production    # use for real WhatsApp sends (e.g. with ngrok)
The docker-compose.yml in the repo defines services (web, db, redis, celery, beat, admin-portal, docs, caddy) and can override or pass these via environment. Ensure .env is in the same directory as docker-compose.yml.

​
3. Run the stack

From the project root: 
docker compose up -d
This starts:
  • web — Flask app (webhooks, API) on port 5050
  • db — PostgreSQL
  • redis — Redis (Celery broker)
  • celery — Celery worker
  • beat — Celery Beat scheduler
  • admin-portal — Admin dashboard on port 5002
  • docs — Documentation site on port 5003
  • caddy — Reverse proxy on ports 80/443 (if used)
Check that containers are up: 
docker compose ps

​
Database migrations

If the database is new, run migrations so tables exist: 
docker compose exec web flask db upgrade
(Requires Flask-Migrate and the migrations/ folder; see Database for how migrations work.)

​
Verify the API

  • Health/DB check (if implemented): curl http://localhost:5050/test-db (from host, if port 5050 is published).
  • Main API is at http://localhost:5050; webhook path is /webhook.

​
4. Optional: run with ngrok (development)

To test the WhatsApp webhook locally with Meta’s servers, expose the Flask app via ngrok: 
docker compose --profile dev up -d
This starts the same services plus ngrok, which gives you a public HTTPS URL forwarding to the web service (port 5050).
  • Open the ngrok dashboard at http://localhost:4040 (or check ngrok container logs) to get the public URL.
  • In Meta’s developer app, set the webhook callback to https://<ngrok-host>/webhook and use verify token test123.
  • Set ENV=production in .env if you want all message types (including plain text and location requests) to be sent to WhatsApp; then restart: docker compose restart web celery beat.
To stop everything including ngrok: 
docker compose --profile dev down
See Ngrok for more on how ngrok is configured in this project.

​
5. Run the docs site locally (optional)

To edit and preview the documentation with hot-reload, from the docs/ directory run: 
mint dev
Install the CLI first if needed: npm i -g mint. The preview runs at http://localhost:3000. Production docs are served at docs.lokpanchang.com via the docs Docker service and Caddy.

​
Next steps

  • Backend — How the Flask app, webhooks, and main modules work.
  • Database — Schema, models, connection, and migrations.
  • Admin portal — Using the admin dashboard and test routes (e.g. Testing routes).
  • Repo root README — Full architecture, logging, and quick reference commands.