Skip to content

Getting Started

This section covers everything you need to set up your development environment and start contributing to the Freeze Design webshop.

Prerequisites

Before you begin, ensure you have the following installed:

  • Python 3.12 or newer (CI runs 3.12; the Docker image is python:3.14-slim)
  • Node.js 22 or newer (CI runs 22; the Docker image is node:26-alpine)
  • PostgreSQL 15 and Redis 7 — normally via Docker: docker-compose.dev.yml provides PostgreSQL, Redis, and RabbitMQ (RabbitMQ is started but unused; Celery uses Redis)
  • Docker Desktop (required by ./manage.sh setup)
  • libmagic (needed by python-magic; the setup script installs it via Homebrew)

Sections

Installation Steps

git clone https://github.com/Voorman/webshop_freeze_design.git
cd webshop_freeze_design
./manage.sh setup

The setup script (scripts/setup-dev.sh) checks the prerequisites, enables the shared git hooks (core.hooksPath .githooks), creates backend/venv and installs requirements.txt, copies backend/.env.example to backend/.env, runs npm install and writes frontend/.env.local, starts the Docker development services, applies migrations, imports the seed data (import_seed_data --mode skip --force) and offers to create a superuser. Flags: --quick (skip the superuser prompt) and --skip-seed.

macOS-oriented

The setup script uses Homebrew to install missing prerequisites (Python, Node.js, libmagic). On Linux install those yourself first, or follow the manual steps in the installation guide.

First Run

./manage.sh start
./manage.sh status

Open http://localhost:3000 for the storefront and http://localhost:8000/api/health/ for the backend health response.

Common Setup Issues

  • Docker is installed but unavailable: start Docker Desktop before rerunning setup or start.
  • Port 5432 is already occupied: stop the local PostgreSQL service so the development container can bind its configured port.
  • Backend configuration is missing: copy backend/.env.example to backend/.env; the setup command normally does this automatically.
  • Frontend packages or Playwright browsers are missing: run npm install or npx playwright install --with-deps from frontend/ as appropriate.

Next Steps

  • Read Configuration before changing environment-specific behavior.
  • Use the Development Guide for build, lint, branch, and pull-request conventions.
  • Use the Testing Guide to select the right local and CI test commands.