> ## Documentation Index > Fetch the complete documentation index at: https://docs.lokpanchang.com/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart > Get the Lok Panchang project running from a fresh clone: prerequisites, environment, and first run 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](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/). * **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](http://localhost:3000)). Production docs are served by the `docs` Docker service. ## 1. Clone the repository ```bash theme={null} git clone cd Panchang-Project ``` Replace `` with your repo URL. ## 2. Environment variables Create a `.env` file in the project root. The application expects at least the following: | Variable | Purpose | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DATABASE_URL` | PostgreSQL connection string (e.g. `postgresql+psycopg2://user:password@db:5432/panchang_db` for Docker; use host `localhost` if connecting from host) | | `CELERY_BROKER_URL` | Redis URL for Celery (e.g. `redis://redis:6379/0`) | | `CELERY_RESULT_BACKEND` | Redis URL for Celery results (e.g. `redis://redis:6379/0`) | | `OPENCAGE_API_KEY` | OpenCage API key for reverse geocoding (required for location → timezone/city) | | `WHATSAPP_PHONE_NUMBER_ID` | WhatsApp Business API phone number ID | | `WHATSAPP_ACCESS_TOKEN` | WhatsApp Business API access token | | `SECRET_KEY` | Flask secret key (used by the admin portal) | | `ENV` | `development` (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):** ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} docker compose ps ``` ### Database migrations If the database is new, run migrations so tables exist: ```bash theme={null} docker compose exec web flask db upgrade ``` (Requires Flask-Migrate and the `migrations/` folder; see [Database](/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: ```bash theme={null} 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](http://localhost:4040)** (or check ngrok container logs) to get the public URL. * In Meta’s developer app, set the webhook callback to `https:///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: ```bash theme={null} docker compose --profile dev down ``` See [Ngrok](/infrastructure/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: ```bash theme={null} mint dev ``` Install the CLI first if needed: `npm i -g mint`. The preview runs at **[http://localhost:3000](http://localhost:3000)**. Production docs are served at **docs.lokpanchang.com** via the `docs` Docker service and Caddy. ## Next steps * **[Backend](/backend)** — How the Flask app, webhooks, and main modules work. * **[Database](/database)** — Schema, models, connection, and migrations. * **[Admin portal](/admin-portal)** — Using the admin dashboard and test routes (e.g. [Testing routes](/guides/testing-routes)). * **Repo root README** — Full architecture, logging, and quick reference commands.