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

========================================
Deployment in the production environment
========================================

:Author: Sixu Wei <reisa@sust.edu.cn>, Zhenyu Yang <yangzhenyu@sust.edu.cn>
:Date:   Mar 24, 2026

This document provides a step-by-step guide for deploying the project in a
production environment.

In production, **Nginx** is used as the reverse proxy, and **Gunicorn** runs
the backend application.

Step 1: Configure environment variables
=======================================

Based on ``prod.env``, create a ``.env`` file in the project root directory.

Database configuration:

.. code-block:: text

   # Database name
   MYSQL_DATABASE=myucspace

   # Database password
   MYSQL_ROOT_PASSWORD=your_secure_password_here

   # Database host
   MYSQL_HOST=db

   # Database port
   MYSQL_PORT=3306

Django configuration:

.. code-block:: text

   # Disable debug mode in production
   DJANGO_DEBUG=false

   # Django secret key (at least 50 characters)
   DJANGO_SECRET_KEY=your_very_long_random_secret_key

   # Allowed hosts
   DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1,example.com

   # CSRF trusted domains (your domain with protocol)
   CSRF_DOMAINS=https://example.com

   # Local upload directory
   LOCAL_UPLOAD_DIR=/data/uploads

   # SM2 keys
   SM2_PUBLIC_KEY=your_sm2_public_key
   SM2_PRIVATE_KEY=your_sm2_private_key

.. warning::

   For security, use strong, unique values for all secrets and keys. Consider
   using a secrets manager or environment variable management tool in
   production.

.. note::

   ``FACE_SERVICE_URL`` is intentionally omitted here. The current Django
   backend and Android signage display flow do not depend on ``face-service``.

WeChat Mini Program configuration:

.. code-block:: text

   # WeChat App ID
   WECHAT_APP_ID=your_wechat_app_id

   # WeChat App Secret
   WECHAT_APP_SECRET=your_wechat_app_secret

WebAuthn configuration:

.. code-block:: text

   # WebAuthn Relying Party ID (your domain)
   WEBAUTHN_RP_ID=example.com

   # WebAuthn Relying Party Name
   WEBAUTHN_RP_NAME='MyUCSpace'

   # WebAuthn Origin (your domain with protocol)
   WEBAUTHN_ORIGIN=https://example.com

Step 2: Build and run
=====================

.. code-block:: bash

   # Build and run
   sudo docker compose -f docker-compose.prod.yml up --build -d

   # Check service status
   sudo docker compose -f docker-compose.prod.yml ps

   # View logs (if any issues occur)
   sudo docker compose -f docker-compose.prod.yml logs -f

Step 3: Initialize the database and create a user
=================================================

.. code-block:: bash

   # Run database migrations
   sudo docker compose -f docker-compose.prod.yml exec backend python manage.py migrate

   # Create an administrator account
   sudo docker compose -f docker-compose.prod.yml exec backend python manage.py createsuperuser

Step 4: Configure HTTPS (optional but recommended)
==================================================

Refer to the :doc:`HTTPS Deployment Guide <https-deployment-guide>` for
detailed instructions on setting up HTTPS with Nginx.

Production access endpoints
===========================

+--------------+-------------------------------+
| Service      | URL                           |
+==============+===============================+
| Frontend     | http://localhost              |
+--------------+-------------------------------+
| Backend API  | http://localhost/api/v1/      |
+--------------+-------------------------------+
| Admin Panel  | http://localhost/django-admin/|
+--------------+-------------------------------+

Domestic (China) image mirror configuration
===========================================

If image pulls fail, configure a Docker mirror registry using the following
command:

.. code-block:: bash

   sudo -i
   bash <(curl -sSL https://linuxmirrors.cn/docker.sh)

See more: `Docker Installation & Registry Mirror Switcher <https://linuxmirrors.cn/en/other>`_.