Install python venv support during Maia deploy

.gitea/workflows/deploy.yml

@@ -112,6 +112,56 @@ jobs:
             exit 1
           fi
 
+          install_apt_package() {
+            package_name="$1"
+            if [ "$(id -u)" -eq 0 ]; then
+              DEBIAN_FRONTEND=noninteractive apt-get install -y "$package_name"
+            elif command -v sudo >/dev/null 2>&1; then
+              sudo DEBIAN_FRONTEND=noninteractive apt-get install -y "$package_name"
+            else
+              return 1
+            fi
+          }
+
+          ensure_python_venv() {
+            probe_dir="$(mktemp -d)"
+            if "$python_bin" -m venv "$probe_dir" >/dev/null 2>&1; then
+              rm -rf "$probe_dir"
+              return 0
+            fi
+            rm -rf "$probe_dir"
+
+            if ! command -v apt-get >/dev/null 2>&1; then
+              echo "Python venv support is missing, and apt-get is not available on the deploy server."
+              return 1
+            fi
+
+            echo "Python venv support is missing. Installing python venv package..."
+            if [ "$(id -u)" -eq 0 ]; then
+              DEBIAN_FRONTEND=noninteractive apt-get update
+            elif command -v sudo >/dev/null 2>&1; then
+              sudo DEBIAN_FRONTEND=noninteractive apt-get update
+            else
+              echo "Cannot install python venv package because deploy user is not root and sudo is unavailable."
+              return 1
+            fi
+
+            python_version="$("$python_bin" -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
+            for package_name in "python${python_version}-venv" "python3-venv"; do
+              if install_apt_package "$package_name"; then
+                probe_dir="$(mktemp -d)"
+                if "$python_bin" -m venv "$probe_dir" >/dev/null 2>&1; then
+                  rm -rf "$probe_dir"
+                  return 0
+                fi
+                rm -rf "$probe_dir"
+              fi
+            done
+
+            echo "failed to install a working python venv package."
+            return 1
+          }
+
           if ! command -v git >/dev/null 2>&1; then
             echo "git is required on the deploy server because maia3 is installed from GitHub"
             exit 1
@@ -137,6 +187,12 @@ jobs:
           }
 
           if [ ! -d "$MAIA_VENV_DIR" ]; then
+            if ! ensure_python_venv; then
+              rollback_maia
+              echo "failed to prepare Python venv support on the deploy server."
+              exit 1
+            fi
+
             if ! "$python_bin" -m venv "$MAIA_VENV_DIR"; then
               rollback_maia
               echo "failed to create Python venv. Install python3-venv on the deploy server."

docs/ci-cd.md

@@ -57,12 +57,13 @@ Gitea repository secrets에 다음 값을 등록한다.
 - Java 21
 - systemd
 - Python 3.11 또는 Python 3
-- Python venv 모듈(`python3-venv` 계열 패키지)
+- Python venv 모듈(`python3-venv` 계열 패키지). 없으면 배포 스크립트가 `apt-get` 또는 `sudo apt-get`으로 자동 설치를 시도한다.
 - `git`
 - `sha256sum`
 - `tar`
 - 외부 네트워크 접근. `requirements.txt`가 `git+https://github.com/CSSLab/maia3.git`를 설치한다.
 - `DEPLOY_USER`가 `/root/blog-backend`에 쓸 수 있고 `/etc/systemd/system`에 서비스 파일을 설치하며 `systemctl`을 실행할 수 있어야 한다.
+- Python venv 패키지가 없는 서버에서는 `DEPLOY_USER`가 `apt-get install`을 실행할 수 있어야 한다. root 접속이 아니면 passwordless sudo 권한이 필요하다.
 
 첫 설치 또는 Maia3 의존성 변경 시 Python 패키지 설치와 모델 캐시 준비 때문에 배포가 오래 걸릴 수 있다. 모델 캐시는 `/root/blog-backend/.cache/huggingface`에 저장된다.