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 (CI) / 3.14 (Docker image) Backend runtime
Node.js 22 (CI) / 26 (Docker image) Frontend runtime
PostgreSQL 15 Database (postgres:15-alpine in docker-compose.dev.yml)
Redis 7 Cache & Celery broker (redis:7-alpine)
Docker Desktop current Runs PostgreSQL and Redis locally
libmagic any Required by python-magic (Homebrew: brew install libmagic)

One-command setup (recommended)

./manage.sh setup is the blessed entry point — it wraps scripts/setup-dev.sh and performs the full setup below (prerequisites check, git hooks, backend venv, frontend install, Docker services, migrations, seed data, optional superuser) in one go. Useful flags:

  • --quick — skip optional steps (superuser creation)
  • --skip-seed — skip seed-data import

The script installs missing prerequisites with Homebrew, so it is macOS-oriented. The manual steps that follow are for Linux, for finer control, or to understand what the script does.

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

The defaults in .env.example already match the Docker development database, so no edit is needed for a standard setup:

DB_NAME=webshop_dev
DB_USER=webshop
DB_PASSWORD=dev_password_123
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 the catalog (products, categories, pricing, decoration methods, print zones, fonts, clipart, pages, site settings) and images from backend/fixtures/seed/. ./manage.sh setup runs it as import_seed_data --mode skip --force. 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

Add celery -A config beat -l INFO if you want the periodic tasks (backups, reminders, guest-design cleanup) locally; the schedule runs in Europe/Amsterdam.

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 (pytest), the frontend TypeScript check, a non-blocking CodeRabbit review and the Jest suite with coverage before every push. A push that only touches docs, Markdown or todo's skips the checks. Enable it with:

git config core.hooksPath .githooks

(./scripts/setup-dev.sh configures this automatically; check with git config --get core.hooksPath.)

Access Points

URL Description
http://localhost:3000 Main webshop (the Next.js admin lives under /admin)
http://localhost:8000/django-admin/ Django admin
http://localhost:8000/api/docs/ API documentation (Swagger UI; schema at /api/schema/)
http://localhost:8000/api/health/ Backend health check

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
npx playwright test --project=chromium --grep @smoke

See the Testing Guide for the full set, including the backend that Playwright needs.

Useful Commands

manage.sh

./manage.sh start | stop | restart | status   # local backend + frontend processes
./manage.sh createsuperuser                   # Django admin account
./manage.sh ci-check                          # migrations, Django test runner, tsc, Jest, ESLint
./manage.sh review [all|uncommitted|committed|plain|prompt] [base]   # CodeRabbit review
./manage.sh loadtest [all|products|cart|upload]                      # k6 (backend must run)
./manage.sh magic-links [email]               # active magic-link codes
./manage.sh export-seed-data | import-seed-data | update-catalog     # see the Seed Data guide

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

# One-off content and read-only status commands
python manage.py vul_categorieteksten --dry-run   # fill empty category texts from categorieteksten.json
python manage.py website_weekcijfers_status        # latest WebsiteWeekSnapshot rows

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/django-admin/

Next Steps