.. SPDX-License-Identifier: GPL-3.0-or-later

==================================
Development environment deployment
==================================

:Author: Sixu Wei <reisa@sust.edu.cn>, Zhenyu Yang <yangzhenyu@sust.edu.cn>
:Date:   Mar 23, 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/django-admin/ |
+--------------+-------------------------------------+

Development vs production comparison
====================================

+------------------+------------------------+---------------------------------+
| Compose file     | ``docker-compose.yml`` | ``docker-compose.prod.yml``     |
+==================+========================+=================================+
| Purpose          | Development            | Production                      |
+------------------+------------------------+---------------------------------+
| Frontend service | Vite dev server        | Nginx static hosting            |
+------------------+------------------------+---------------------------------+
| Backend service  | ``runserver``          | Gunicorn                        |
+------------------+------------------------+---------------------------------+
| Ports            | 3000, 8000             | 80 or 443 (when TLS is enabled) |
+------------------+------------------------+---------------------------------+

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