Development environment deployment

Author:

Sixu Wei <reisa@sust.edu.cn>, Zhenyu Yang <yangzhenyu@sust.edu.cn>

Last updated:

Jan 24, 2026

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

Quick start

Configure environment variables

Rename dev.env to .env in the project root directory.

mv dev.env .env

Note

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

Development vs production comparison

Compose file

Purpose

Frontend service

Backend service

Ports

docker-compose.dev.yml

Development

Vite dev server

runserver

3000, 8000

docker-compose.yml

Production

Nginx static hosting

Gunicorn

80

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