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¶
Start PostgreSQL & Redis (Docker)¶
The dev compose file provides PostgreSQL (port 5432) and Redis (port 6379) with credentials matching .env.example:
Backend Setup¶
Create Virtual Environment¶
Install Dependencies¶
Environment Configuration¶
Copy the example environment file and configure it:
The defaults in .env.example already match the Docker development database, so no edit is needed for a standard setup:
Database Setup¶
Load Seed Data (Optional)¶
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¶
Environment Configuration¶
Edit .env.local:
Running the Application¶
Start Backend¶
Backend will be available at: http://localhost:8000
Start Frontend¶
Frontend will be available at: http://localhost:3000
Start Celery Worker (Optional)¶
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:
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:
(./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¶
- Create the serializer in
backend/apps/<app>/serializers.py - Create the viewset in
backend/apps/<app>/views.py - Register in
backend/config/urls.pyrouter - Test at
http://localhost:8000/api/docs/
Adding a New React Component¶
- Create component in
frontend/components/ - Add types to
frontend/types/index.tsif needed - Create Storybook story in same directory
- Run
npm run storybookto preview
Running Tests¶
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¶
- Open
http://localhost:3000in your browser - You should see the Freeze Design homepage
- Access Django admin at
http://localhost:8000/django-admin/
Next Steps¶
- Configuration - Customize your environment
- Architecture Overview - Understand the system design
- Testing Guide - Write effective tests
- Deployment Guide - Deploy to staging and production