Shoppy E‑Commerce App

Full‑stack e‑commerce demo built with:

• Backend: Django 6, Django REST Framework, JWT auth, MySQL
• Frontend: React, TypeScript, Vite, Tailwind CSS
• Containerization: Docker, Docker Compose (includes MySQL)

You can run everything with Docker (recommended) or run backend/frontend locally.

---

1. Prerequisites

Option A – Run with Docker (recommended)

• Docker Desktop (Windows/macOS) or Docker Engine + Docker Compose (Linux)

You do not need MySQL installed on your host. Docker Compose will start a MySQL container for you.

Option B – Run locally (no Docker)

• Python 3.12+
• Node.js 18+ (for the Vite frontend)
• MySQL server (if you want to use the same DB config as Docker)

Backend dependencies are managed via Pipfile/Pipfile.lock (Pipenv) for local dev and Backend/requirements.txt for Docker.

---

2. Quick Start with Docker Compose

From the project root (E-Commerce):

cd /d B:\vsCode\Django\E-Commerce
docker compose up --build

The first run will:

• Pull and start a MySQL 8 container (db service)
• Build the web image (frontend build + Django backend)
• Run Django migrations
• Start:
  • Backend API on http://localhost:8000
  • Frontend SPA on http://localhost:5173

To run in the background:

cd /d B:\vsCode\Django\E-Commerce
docker compose up --build -d

To stop everything:

cd /d B:\vsCode\Django\E-Commerce
docker compose down

Data is stored in the named Docker volume e-commerce_db_data, so containers can be recreated without losing DB contents.

---

3. Services Overview

3.1 db (MySQL)

Defined in docker-compose.yml:

• Image: mysql:8.0
• Database: shoppy
• User: root
• Password: password

Environment variables inside the container:

• MYSQL_DATABASE=shoppy
• MYSQL_ROOT_PASSWORD=password

3.2 web (Frontend + Backend)

Builds from the root Dockerfile:

• Stage 1: builds the React frontend (Vite, TypeScript)
• Stage 2: installs Python dependencies and runs Django

Environment variables (set in docker-compose.yml):

• DB_HOST=db
• DB_NAME=shoppy
• DB_USER=root
• DB_PASSWORD=password
• DB_PORT=3306

These are read by Backend/shoppy/settings.py to configure Django’s DATABASES setting.

---

4. Using the App

Once docker compose up is running:

• Frontend: http://localhost:5173
• Backend root (example): http://localhost:8000/
• Products API: http://localhost:8000/api/products/

4.1 Typical Flows

Customer

1. Go to http://localhost:5173 (Home page)
2. Register as a customer
3. Log in as a customer
4. Browse products and add to cart
5. View cart and checkout (creates orders)
6. View past orders

Seller

1. Visit seller auth pages via navigation (Seller Login / Register)
2. Register as a seller
3. Log in as a seller
4. Go to the Seller Products page
5. Create products and manage inventory

Unauthenticated visitors can view products; only sellers/admins can create or modify products.

---

5. Seeding Sample Products

The backend includes a management command to seed sample products.

Inside the running web container:

# From your host
cd /d B:\vsCode\Django\E-Commerce
docker compose exec web python Backend/manage.py seed_products

This command is idempotent: it will only create missing sample products.

---

6. Running Locally Without Docker

You can also run backend and frontend directly on your host for development.

6.1 Backend (Django)

1. Create and activate a virtual environment (Pipenv example):

cd /d B:\vsCode\Django\E-Commerce
pipenv install
pipenv shell

2. Make sure MySQL is running and update Backend/shoppy/settings.py DB env vars as needed on your host (or set environment variables DB_HOST, DB_NAME, DB_USER, DB_PASSWORD, DB_PORT).

3. Run migrations and start the dev server:

cd /d B:\vsCode\Django\E-Commerce
cd Backend
python manage.py migrate
python manage.py runserver 0.0.0.0:8000

6.2 Frontend (Vite + React)

In a separate terminal:

cd /d B:\vsCode\Django\E-Commerce\Frontend
npm install
npm run dev

By default, Vite runs on http://localhost:5173 and proxies or directly calls the backend at http://localhost:8000 (depending on your API client configuration).

---

7. Environment Variables

The backend reads DB configuration from environment variables (with sensible defaults):

• DB_HOST (default: 127.0.0.1)
• DB_NAME (default: shoppy)
• DB_USER (default: root)
• DB_PASSWORD (default: empty string)
• DB_PORT (default: 3306)

When using Docker Compose, these are set for you in docker-compose.yml.

---

8. Running Tests (Backend)

With your local Python environment active (Pipenv shell):

cd /d B:\vsCode\Django\E-Commerce\Backend
python manage.py test

This runs the Django test suite for users, products, cart, and orders apps.

---

9. Troubleshooting

• Docker Desktop / WSL issues (Windows)

  • Ensure Docker Desktop is running and WSL 2 is installed and enabled.

  • From an elevated PowerShell:

    wsl --shutdown
    wsl --update
    wsl --status

• Port conflicts

  • If 8000 or 5173 are already in use, stop the other service or change the published ports in docker-compose.yml.

• Database connection errors

  • Confirm the db service is healthy: docker compose ps.
  • Check logs: docker compose logs db and docker compose logs web.

If you run into issues, double-check the Docker logs and environment variables first; most problems are configuration‑related.