Skip to content

BITNP/contest-bitnp

Repository files navigation

contest-bitnp 国防知识竞赛

Check pre-commit.ci status Dockerhub image

目录

开发

技术细节请参考doc/

Note

还可参考 GitHub Actions

开始

⚒️ 安装工具

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

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

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

  • 配置

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

    $ poetry config virtualenvs.in-project true

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

  • 功能:本项目源代码不在根目录,有许多命令执行时有 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”的位置。

  • 功能:构建前端 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-jsjust 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.tomltool.poetry.dependenciestool.poetry.group.deploy.dependencies转换为requirements.txt

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

Note

现在仓库中的requirements.txt还手动删除了python_versionsys_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

手动部署

需要 poetryjust,安装方法及配置请参考上文。

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