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.ymlprovides PostgreSQL, Redis, and RabbitMQ (RabbitMQ is started but unused; Celery uses Redis) - Docker Desktop (required by
./manage.sh setup) libmagic(needed bypython-magic; the setup script installs it via Homebrew)
Sections¶
- Installation - Set up your local development environment
- Configuration - Environment variables and settings
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¶
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.exampletobackend/.env; the setup command normally does this automatically. - Frontend packages or Playwright browsers are missing: run
npm installornpx playwright install --with-depsfromfrontend/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.