==========
 部署手册
==========

本文档主要说明如何在 Linux 服务器上部署 易科 1.0 系统。

.. contents:: 内容
   :depth: 2
   :local:
   :backlinks: top

服务器环境
==========

服务器需要安装的软件

- Nginx 1.18.0
- Python 3.10
- Djanjo 5.0+
- MariaDB 10.0+
- Supervisor

初始部署
========

第一次或者在全新环境进行部署的说明。

发布的文件直接从 GitHub 库 `dashingsoft/eke`__ 的发布中获取

第一次发布的版本号 `v0.1`__

.. note::

   用户需要权限才能访问 Github 库，用户启用 2fa 的简单方式:

   - 选择使用 App 方式验证，会弹出一个二维码
   - 使用微信扫描该二维码，会显示其对应的文本，其中 TOKEN 对应的是一串字符，例如 `EHILBUEILMSHNK`
   - 安装 Python 包 `pip install pyotp`
   - 执行下面的 Python 语句，注意需要替换 `EHILBUEILMSHNK` 为实际值

     .. code-block:: bash

        $ python
        >>> import pyotp
        >>> pyotp.TOTP("EHILBUEILMSHNK").now()
        580286
   - 把最后打印出来的一串数字输入到 Github 验证页面即可

__ https://github.com/dashingsoft/eke
__ https://github.com/dashingsoft/eke/releases/tag/v0.1

输入文件
--------

第一次发布的文件包 `eke-0.1-py310.tar.gz`__ 解压后的目录:

- src/ 包括 Django 工程的源文件和其他相关的 Python 包
- meta/ 相关的模版文件
- webroot/ 所有需要放到 Web 服务器下面的文件

__ https://github.com/dashingsoft/eke/releases/tag/v0.1

服务器目录
----------

第一次发布需要在服务器上创建一些目录

- 代码目录，默认是 `/opt/eke/` ，子目录对其他用户只读，包括

  - src/ 存放发布包中 `src` 下面的文件
  - meta/ 存放发布包中 `meta` 下面的文件
  - bin/ 存放辅助脚本

- 数据目录，默认是 `/var/eke/` ，子目录需要 web 用户可读可选，包括

  - usr/ 存放注册用户的数据
  - fly/ 存放临时用户的数据

- 网站根目录，存放发布包中的 `webroot` 中的文件

- 创建目录链接 `/opt/eke/src/ekengineer`

  .. code-block:: bash

     cd /opt/eke/src
     ln -s /opt/eke/meta/ekengineer

MariaDB 配置
------------

创建数据库 `ekedb`

参考 `Writing your first Django app, part 2`__

__ https://django.readthedocs.io/en/stable/intro/tutorial02.html

Django 配置
-----------

Django 的配置文件为 `src/ekesite/settings.py` 需要进行相关的配置

- SECRET_KEY 使用外部文件
- STATIC_URL 默认配置为 `https://eke.dashingsoft.com/static/`
- DEBUG 必须修改为 `False`
- ALLOWED_HOSTS 默认配置为 `['eke.dashingsoft.com']`
- DATABASES 配置为使用 MariaDB 引擎的 `ekedb`

参考 `Django Deployment checklist`__

接下来创建数据表::

  $ cd /opt/eke/src
  $ rm -rf {tasks,works,stacks}/migrations
  $ python manage.py makemigrations
  $ python manage.py migrate

以及后台管理超级用户::

  $ python manage.py createsuperuser

参考 `Writing your first Django app, part 2`__

__ https://django.readthedocs.io/en/stable/howto/deployment/checklist.html#critical-settings
__ https://django.readthedocs.io/en/stable/intro/tutorial02.html

配置 Supervisor 后台启动 Django
-------------------------------

创建 Django 的启动脚本 `/opt/eke/bin/start-server.sh`:

.. code-block:: bash

  cd /opt/eke/src
  python manage.py runserver 20528

创建配置文件 `/etc/supervisor/eke.conf`:

.. code-block:: ini

   [program:eke]
   command=bash bin/start-server.sh
   user=eke
   directory=/opt/eke
   stopwaitsecs=60
   stopasgroup=true
   stdout_logfile=/opt/eke/log/supervisor_stdout.log
   stderr_logfile=/opt/eke/log/supervisor_stderr.log
   autostart = true

配置 Nginx
----------

外部访问地址 `https://eke.dashingsoft.com`

需要把下列路径的请求转发到 Django 后台

- /admin/
- /api/
- /pub/

参考配置如下:

.. code-block:: nginx

  server {
      server_name eke.dashingsoft.com;
      ...
      location /admin/ {
        proxy_pass http://localhost:20528/admin/;
      }
      location /pub/ {
        proxy_pass http://localhost:20528/pub/;
      }
      location /api/ {
        proxy_pass http://localhost:20528/api/;
      }
  }

文档发布
--------

使用下面的脚本进行发布:

.. code-block:: bash

  $ cd /path/to/eke/docs
  $ make build
  $ cp _build/html /path/to/webroot/docs/

更新部署
========

在发布版本升级之后的部署说明。

每次更新之后会有新的版本号 `X.Y`

输入文件
--------

根据输入的版本号 `X.Y` 可以从下面的地址::

  https://github.com/dashingsoft/eke/releases/tag/vX.Y

下载发布包 `eke-X.Y-py310.tar.gz`

注意需要替换 `X.Y` 为实际的版本号，例如 `0.2`

发布的文件包解压后的目录基本同第一次发布是一样的

- src/
- meta/
- webroot/

分别拷贝到相应的服务器目录，覆盖原来的文件

如果数据库结构发上了变化，需要执行下面的更新:

.. code-block:: bash

   $ cd /opt/eke/src
   $ python manage.py makemigrations
   $ python manage.py migrate