Skip to content

Latest commit

 

History

History
322 lines (222 loc) · 9.68 KB

README.md

File metadata and controls

322 lines (222 loc) · 9.68 KB
Raw

contest-bitnp 国防知识竞赛

Check pre-commit.ci status Dockerhub image

目录

开发

技术细节请参考doc/。

Note

还可参考 GitHub Actions。

开始

⚒️ 安装工具

Poetry

  • 功能：本项目使用 Poetry 管理 python 包。

    例如poetry shell可在终端直接使用虚拟环境。

  • 安装方法：请参阅 Introduction | Documentation | Poetry。

  • 配置

    完成安装后，建议您选择将虚拟环境放在项目中：

    $ poetry config virtualenvs.in-project true

    原因：这样poetry install时会在项目所在文件夹创建.venv/，比C:/Users/…/AppData/Local/pypoetry/Cache/…或~/.cache/pypoetry/…更明显。

Just

  • 功能：本项目源代码不在根目录，有许多命令执行时有 tricks。因此建议安装 just，用 just 调用。

    例如，运行 mypy 时，必须使用正确配置在正确的位置运行。

    $ just --list  # 列出可用任务

  • 安装方法（Unix）

    建议参考 Packages - Just Programmer's Manual，使用包管理器安装。

  • 安装方法（Windows）

    下载编译好的可执行文件，解压出just.exe，放到$PATH环境变量包含的任意地方。另外也可用包管理器 scoop 安装：

    > scoop install just

    在 Windows 上，除了 just，您还需要选个 shell。至少有下面几种选择。

    • 将C:/Program Files/Git/bin/添加到$PATH环境变量，使用 Git for Windows 附带的 Git Bash（sh.exe）。

    • 也使用 Git Bash，但不用环境变量，而用 scoop 包装：创建~/scoop/shims/sh.shim，写入path = "C:/Program Files/Git/usr/sh.exe"。

    • 编辑项目根目录的justfile，使用 Command Prompt 或 PowerShell。

      # 在 justfile 开头加上以下任意一行
set shell := ["cmd.exe", "/c"]
set shell := ["powershell.exe", "-c"]
# 更改后请勿提交到仓库中，因为CI和每人的设备不一样。

    Note

    C:/Program Files/Git/指 Git 的安装目录。

    另外注意是…/Git/bin/，而非…/Git/usr/bin/。

    Note

    可用--shell临时测试，例如：

    $ just --shell 'C:/Program Files/Git/usr/bin/bash.exe' …

  • 配置

    如果需控制 just 使用哪个 python，请在项目根目录创建.env文件，设置PYTHON变量。下面是一些例子。

    # 使用项目中的虚拟环境
PYTHON = "./.venv/Scripts/python.exe"

# 使用 poetry 缓存中的环境
PYTHON = "C:/Users/bjalp/AppData/Local/pypoetry/Cache/virtualenvs/…/python.exe"

# 直接调用 poetry（万能，但比较慢）
PYTHON = "poetry run python"

    Note

    poetry install创建虚拟环境后，可用poetry env info查看“Executable”的位置。

Pnpm

  • 功能：构建前端 CSS 和 JavaScript。

  • 安装方法

    1. 前往 Node.js 网站，下载并安装 v18 LTS。（安装结束后会提示安装 choco，可取消勾选）

    2. 使用 corepack 安装 pnpm。

      $ corepack enable
$ corepack prepare pnpm@latest --activate

    Note

    也可尝试 Installation | pnpm 介绍的其它方法。

👢 安装包

初次使用时，需要安装项目依赖的包并创建数据库：

$ just update

以后拉取他人提交后，如果他人更新了依赖或更改了数据模型，你可能无法继续开发，此时也请just update。

🏃‍♀️ 启动服务器

  1. 构建前端。

    $ just build-js build-theme

    Note

    如果你想更改前端代码，可just watch-js、just watch-theme来自动重新构建。

  2. 启动 Django 服务器。

    $ just serve

  3. 访问 localhost:8000，用户名、密码请咨询他人。

✅ 检查

  • 代码质量

    $ just check-all

    这会检查类型、运行测试等。

  • 格式（可选）

    本项目配置了 pre-commit，可自动格式化代码、检查错别字等。

    如果你想使用它，那么可用 pip 或 pipx 安装 pre-commit，然后运行pre-commit install。此后提交到仓库时会自动检查格式。

    Note

    git commit --no-verify可绕过 pre-commit。

VS Code

任务

部分 just 命令配备了 problem matcher。Ctrl+P，输入task及空格，按提示操作可运行。

Django 魔法

VS Code 默认的 Pylance 无法识别很多 Django 魔法（如*_set）。可考虑禁用之，代以 Matan Gover 的 Mypy。（也可并用）这需要你在工作区设置mypy.dmypyExecutable，目前的设置仅适用于 Windows。

部署

容器部署

准备工作

为减小镜像，用 pip 替代 poetry，需将pyproject.toml的tool.poetry.dependencies、tool.poetry.group.deploy.dependencies转换为requirements.txt。

$ poetry export --output requirements.txt --without-hashes --without-urls --with deploy

Note

现在仓库中的requirements.txt还手动删除了python_version、sys_platform，没考虑 python 版本、操作系统不同的问题。之后出问题了再改。

构建容器镜像

$ git clone https://github.com/BITNP/contest-bitnp
$ cd contest-bitnp
$ docker build -t everything411/contest-bitnp .

构建过程中会做以下几件事：

  1. 用 pnpm 构建前端。
  2. 设置用于生产的环境变量。
  3. 安装依赖，整理静态文件，添加题库，启动服务。

从头开始使用容器进行部署

编写docker-compose.yml

version: "3"
services:
  web:
    image: everything411/contest-bitnp
    ports:
      - 8080:80
    environment:
      - SECRET_KEY=${SECRET_KEY}
      - DJANGO_PRODUCTION=1
    volumes:
     - ./db:/usr/src/app/db              # 数据库持久化
     - ./fixtures:/usr/src/app/fixtures  # 放fixtures，加载题目用
     # - ./settings.py:/usr/src/app/contest/settings.py # 取消注释可临时调整设置

然后

$ mkdir db
$ docker compose up -d

然后进去容器内部，创建超级管理员账号，导入：

$ docker exec -it contest_web_1 bash
(in container) # python manage.py createsuperuser
(in container) # python manage.py loaddata fixtures/*.yml

手动部署

需要 poetry、just，安装方法及配置请参考上文。

Note

可用python -m venv替代 poetry，手动执行替代 just。

$ export DJANGO_PRODUCTION="任何非空字符串"
$ export SECRET_KEY="The secret key must be a large random value and it must be kept secret"

$ echo 'PYTHON = "./.venv/bin/python"' > .env
$ just update  # 安装依赖、数据库等
$ just check-deploy  # 检查

Note

若希望部署时永远开放答题，请export DJANGO_DISABLE_QUIZ_OPENING_TIME_INTERVAL="任何非空字符串"。

在 poetry 中安装部署依赖组后，可以使用 uvicorn 或者 gunicorn 来运行本网站：

使用 uvicorn 单线程运行：

$ export DJANGO_PRODUCTION=1
$ export SECRET_KEY="!!replace me replace me!!"
$ cd contest-bitnp
$ uvicorn contest.asgi::application

或者使用 gunicorn 管理多个 uvicorn 工作进程：

$ export DJANGO_PRODUCTION=1
$ export SECRET_KEY="!!replace me replace me!!"
$ cd contest-bitnp
$ gunicorn -w 4 -k uvicorn.workers.UvicornWorker contest.asgi:application

另请参阅 How to deploy Django | Django documentation | Django。