Development Environment Deployment

This document describes how to run the project locally in a development environment using Docker Compose.

It covers environment configuration, initialization, access endpoints, and frequently used commands.

Prerequisites

• Docker Engine and Docker Compose v2

• A Linux host is recommended; Windows/macOS users should use Docker Desktop for a smoother experience

• Make sure ports 3000 and 8000 are not occupied

Services

The development Docker Compose file (docker-compose.yml) includes the following services:

Service	Description
db	PostgreSQL 18 database
redis	Redis 7 — Celery broker, result backend, and Django cache
backend	Django runserver (hot-reload)
celery-worker	Celery worker (concurrency=2, hot-reload)
celery-beat	Celery beat scheduler (DatabaseScheduler, schedule data stored in PostgreSQL)
frontend	Vite dev server
vitepress	Documentation server (VitePress)

Quick Start

Configure Environment Variables

Create a .env file in the project root directory. Development needs at least:

POSTGRES_PASSWORD=password
DJANGO_DEBUG=true
SM2_PUBLIC_KEY=your_sm2_public_key
SM2_PRIVATE_KEY=your_sm2_private_key

All other variables have development-friendly defaults. To override database names, WeChat keys, object storage, package mirrors, or other settings, see Environment Variables.

TIP

The .env file is loaded automatically by Docker Compose. Do not commit .env to version control (add it to .gitignore).

Initialize the System

# Build and start all services
docker compose up --build -d

# Apply database migrations
docker compose exec backend python manage.py migrate

# Create an administrator account
docker compose exec backend python manage.py createsuperuser

Access Endpoints

Service	URL
Frontend	http://localhost:3000
Backend API	http://localhost:8000/api/v1/
Admin Panel	http://localhost:8000/django-admin/

Development vs Production Comparison

Setting	docker-compose.yml	docker-compose.prod.yml
Purpose	Development	Production
Frontend service	Vite dev server	Nginx static hosting
Backend service	runserver	Gunicorn
Celery worker	concurrency=2	concurrency=4
Redis	No persistence	AOF persistence enabled
Ports	3000, 8000	80 or 443 (when TLS is enabled)

Common Commands

# Stop and remove containers (keeps volumes by default)
docker compose down

# Restart all services
docker compose restart

# Follow backend logs
docker compose logs -f backend

# Open a shell inside the backend container
docker compose exec backend bash

# Rebuild and restart a single service (backend as an example)
docker compose up --build -d backend

# Show container status
docker compose ps

Reset the Environment (Remove Data Volumes)

Use the following commands to wipe persistent data (e.g., database volumes) and recreate everything from scratch.

WARNING

This will delete all local development data in Docker volumes.

docker compose down -v
docker compose up --build -d

Troubleshooting Tips

• If the frontend cannot reach the backend, verify the backend container is healthy and that the API base URL matches http://localhost:8000.

• If docker compose up fails due to port conflicts, change host port mappings in docker-compose.yml or stop the conflicting processes.

• When database migrations fail, check backend logs first:

  docker compose logs -f backend