==================================
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.

.. code-block:: bash

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

.. code-block:: bash

   # 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
===============

.. code-block:: bash

   # 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.

.. code-block:: bash

   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:

  .. code-block:: bash

     docker compose logs -f backend