Skip to content

Installation

This guide walks you through setting up the Freeze Design webshop for local development.

Prerequisites

Software Minimum Version Purpose
Python 3.12+ Backend runtime
Node.js 22+ Frontend runtime
PostgreSQL 15+ Database
Redis 7+ Cache & Celery broker

Automated setup

./scripts/setup-dev.sh performs the full setup below (prerequisites check, backend venv, frontend install, Docker services, seed data) in one go.

Clone the Repository

git clone https://github.com/Voorman/webshop_freeze_design.git
cd webshop_freeze_design

Start PostgreSQL & Redis (Docker)

The dev compose file provides PostgreSQL (port 5432) and Redis (port 6379) with credentials matching .env.example:

docker compose -f docker-compose.dev.yml up -d db redis

Backend Setup

Create Virtual Environment

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install Dependencies

pip install -r requirements.txt

Environment Configuration

Copy the example environment file and configure it:

cp .env.example .env

Edit .env and set your database credentials:

DB_NAME=webshop_dev
DB_USER=webshop
DB_PASSWORD=your_password
DB_HOST=localhost
DB_PORT=5432

Database Setup

python manage.py migrate
python manage.py createsuperuser

Load Seed Data (Optional)

python manage.py import_seed_data

This imports products, categories, pricing, and images from backend/fixtures/seed/. See the Seed Data guide for options like --clear and --mode.

Frontend Setup

Install Dependencies

cd frontend
npm install

Environment Configuration

cp .env.example .env.local

Edit .env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000/api

Running the Application

Start Backend

cd backend
python manage.py runserver

Backend will be available at: http://localhost:8000

Start Frontend

cd frontend
npm run dev

Frontend will be available at: http://localhost:3000

Start Celery Worker (Optional)

cd backend
celery -A config worker -l INFO

Development Workflow

Open three terminal windows:

cd backend
source venv/bin/activate
python manage.py runserver

cd frontend
npm run dev

cd backend
source venv/bin/activate
celery -A config worker -l INFO

Git Hooks

A pre-push hook at .githooks/pre-push runs a backend test subset, the frontend TypeScript check, and the Jest suite (plus a non-blocking CodeRabbit review) before every push. Enable it with:

git config core.hooksPath .githooks

(./scripts/setup-dev.sh configures this automatically.)

Access Points

URL Description
http://localhost:3000 Main webshop
http://localhost:8000/admin Django admin
http://localhost:8000/api/docs/ API documentation

Common Tasks

Adding a New API Endpoint

  1. Create the serializer in backend/apps/<app>/serializers.py
  2. Create the viewset in backend/apps/<app>/views.py
  3. Register in backend/config/urls.py router
  4. Test at http://localhost:8000/api/docs/

Adding a New React Component

  1. Create component in frontend/components/
  2. Add types to frontend/types/index.ts if needed
  3. Create Storybook story in same directory
  4. Run npm run storybook to preview

Running Tests

cd backend
pytest

cd frontend
npm run test

cd frontend
npm run test:e2e

Useful Commands

Backend

# Create migrations
python manage.py makemigrations

# Apply migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Shell access
python manage.py shell

# Validate OpenAPI schema
python manage.py spectacular --validate

Frontend

# Development server
npm run dev

# Production build
npm run build

# Linting
npm run lint

# Storybook
npm run storybook

# TypeDoc
npm run docs:typedoc

Verify Installation

  1. Open http://localhost:3000 in your browser
  2. You should see the Freeze Design homepage
  3. Access Django admin at http://localhost:8000/admin

Next Steps