Skip to main content

Local Development

Run all five Nova Print apps on one machine against a local Django API. Local defaults use SQLite and disk uploads when DATABASE_URL and R2_BUCKET_NAME are empty (.env.example, docs/DEPLOYMENT.md).

For architecture context, see Architecture overview. Auth token endpoints are summarized in Authentication.

Prerequisites​

  • Python 3 with venv (backend)
  • Node.js + npm (all frontends ship package-lock.json; use npm install)
  • Copy env templates before starting apps (details in Environment variables)

Default local ports​

AppFolderDev commandPort / URL
APIbackend-main/python manage.py runserverhttp://localhost:8000 (/api/)
Adminfrontend-admin-dashboard/npm run devhttp://localhost:3000 (vite.config.ts)
POSfrontend-pos/npm run devhttp://localhost:3001
Checkoutprintbazar-checkout/npm run devhttp://localhost:3002 (README (printbazar-checkout/README.md))
Storefrontend-ecommerce/npm run devhttp://localhost:3003 (next dev -p 3003)

Backend URL helpers that mint POS / checkout links use matching defaults: POS_FRONTEND_BASE_URL=http://localhost:3001, CHECKOUT_FRONTEND_BASE_URL=http://localhost:3002 (backend-main/.env.example). POS builds customer-link URLs via VITE_CHECKOUT_BASE_URL and frontend-pos/src/lib/publicUrls.ts. Admin builds POS open URLs via VITE_POS_BASE_URL and frontend-admin-dashboard/src/lib/publicUrls.ts.

1. Backend (backend-main/)​

From AGENTS.md and the root / backend env examples:

cd backend-main
python3 -m venv env   # or .venv — activate whatever you create
source env/bin/activate
pip install -r requirements.txt

Env file:

  • Prefer copying .env.example or backend-main/.env.example to backend-main/.env.
  • Set SECRET_KEY. Leave DATABASE_URL and R2_BUCKET_NAME empty for SQLite + local media.
  • With DEBUG=True and empty CORS_ALLOWED_ORIGINS, Django already allows the local frontend origins (3000–3003).

Database and admin user:

python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Optional local archive scheduler (separate process, not inside gunicorn):

python manage.py runapscheduler

See docs/ARCHIVE_SCHEDULER_DEPLOY.md § Local.

Tests: python manage.py test (or a single test path as in AGENTS.md).

2. Admin dashboard (frontend-admin-dashboard/)​

cd frontend-admin-dashboard
npm install
npm run dev

Dev env is checked in as frontend-admin-dashboard/.env.development (VITE_API_BASE_URL, VITE_POS_BASE_URL, VITE_STOREFRONT_URL).

  • Sign in with the Django superuser / staff account (JWT — see Authentication).
  • Superuser-only SQL editor: open /sql-editor by URL (no sidebar link). Details: docs/SQL_EDITOR.md.

Tests: npm run test / npx vitest.

3. POS (frontend-pos/)​

cd frontend-pos
npm install
npm run dev

Uses frontend-pos/.env.development: VITE_API_BASE_URL, VITE_CHECKOUT_BASE_URL=http://localhost:3002. Create a POS terminal in Admin, then open the POS URL built from the slug (buildPosUrl).

4. Checkout (printbazar-checkout/)​

cd printbazar-checkout
npm install
npm run dev

Requires VITE_API_BASE_URL=http://localhost:8000/api (README (printbazar-checkout/README.md), printbazar-checkout/.env.development). Open a customer or catalog link copied from POS (host must be the checkout app on port 3002, not a catalog path under the store).

5. Ecommerce storefront (frontend-ecommerce/)​

cd frontend-ecommerce
npm install
npm run dev

Uses frontend-ecommerce/.env.development: NEXT_PUBLIC_API_BASE_URL, NEXT_PUBLIC_SITE_URL=http://localhost:3003.

Razorpay (optional for COD-only): keys live in the backend .env; enable methods in Admin → Ecommerce → Payment Options. Local webhooks need a tunnel — see docs/RAZORPAY_SETUP.md.

Suggested startup order​

  1. Backend (runserver)
  2. Admin (create POS / products / settings)
  3. POS + Checkout (link flows)
  4. Storefront (ecommerce cart / COD / Razorpay)