fofanov.dmitry/configure_nginx_manager

Fork 0

Files

Dmitriy Fofanov 491db2d5bf

Синхронизация Wiki / Синхронизация Wiki (push) Successful in 2s

Details

Исправлены опечатки и улучшена читаемость документации

2026-02-25 07:54:18 +03:00

21 KiB

Raw Permalink Blame History

Сборка и релизы

Проект поддерживает сборку исполняемых файлов через PyInstaller.

Быстрый старт

make build — сборка для текущей ОС
make build-linux — сборка для Linux
make build-windows — сборка для Windows
make release — сборка + упаковка (linux tar.gz + windows zip) + checksums

Результаты появляются в папке dist/.

Что важно понимать

бинарник получается крупным (~40–60 МБ)
системный certbot всё равно нужен
кросс-компиляция (Windows→Linux, Linux→Windows) обычно не рекомендуется

Пакеты релиза

Linux: letsencrypt-regru-linux-x86_64.tar.gz
Windows: letsencrypt-regru-windows-x86_64.zip

Автоматические релизы по тегам

Типовой сценарий:

создать тег:

git tag -a v1.0.0 -m "Release 1.0.0"

отправить тег:

git push origin v1.0.0

Далее CI (GitHub Actions / Gitea Actions) может автоматически:

собрать артефакты
создать Release
прикрепить файлы

Подробности зависят от ваших workflows.

Ручной запуск релиза (workflow_dispatch)

Если в workflow релиза включён workflow_dispatch, его можно запускать вручную:

из UI Actions
или через Makefile (API dispatch):

make ci-release TAG=v1.0.0

Для запуска через Makefile нужен токен (любой из): DFGIT_TOKEN / GIT_TOKEN / GITEA_TOKEN / GITEA_ACCESS_TOKEN. Makefile отправляет запрос на DFGIT_URL (по умолчанию https://gitea.example.com) в репозиторий DFGIT_REPO.

Appendix (migrated from docs/QUICKSTART_BUILD.md)

🎯 Быстрый старт - Сборка исполняемых файлов

Это краткое руководство для тех, кто хочет быстро собрать исполняемый файл.

Для Linux

1. Установите зависимости

sudo apt-get update
sudo apt-get install -y python3 python3-pip git make

2. Клонируйте репозиторий

git clone https://github.com/DFofanov/configure_nginx_manager.git
cd configure_nginx_manager

3. Соберите

make build-linux

4. Результат

ls -lh dist/letsencrypt-regru
## Исполняемый файл готов!

5. Установите (опционально)

sudo cp dist/letsencrypt-regru /usr/local/bin/
sudo chmod +x /usr/local/bin/letsencrypt-regru

6. Используйте

letsencrypt-regru --help

Для Windows

1. Установите Python

Скачайте с python.org и установите

2. Клонируйте репозиторий

git clone https://github.com/DFofanov/configure_nginx_manager.git
cd configure_nginx_manager

3. Соберите

make build-windows

4. Результат

dir dist\letsencrypt-regru.exe
## Исполняемый файл готов!

5. Используйте

.\dist\letsencrypt-regru.exe --help

Создание релиза для обеих платформ

## Это создаст пакеты для Linux и Windows
make release

Результат в dist/:

letsencrypt-regru-linux-x86_64.tar.gz
letsencrypt-regru-windows-x86_64.zip

Полезные команды

## Показать справку по всем командам
make help

## Информация о среде сборки
make build-info

## Протестировать собранный файл
make test-build

## Очистить артефакты
make clean-build

❓ Проблемы?

См. BUILD_GUIDE.md для подробных инструкций и решения проблем.

Размер файла: ~40-60 MB (включая Python runtime)
Время сборки: ~2-5 минут
Требования: Python 3.8+, PyInstaller

Appendix (migrated from docs/BUILD_GUIDE.md)

🔨 Руководство по сборке исполняемых файлов

Данное руководство описывает процесс компиляции Python скрипта letsencrypt_regru_api.py в исполняемые файлы для Linux и Windows с использованием PyInstaller.

✅ Преимущества исполняемых файлов

Плюсы:

✅ Один файл - легко распространять и развертывать
✅ Автономность - не требует установленного Python на целевой системе
✅ Все зависимости включены - requests, cryptography и certbot модули упакованы
✅ Простота запуска - просто скачать и запустить

Минусы:

❌ Большой размер - ~40-60 MB (включая Python runtime и библиотеки)
❌ Certbot зависимость - системный certbot все равно требуется
❌ Медленный первый запуск - распаковка занимает несколько секунд
❌ Требуется пересборка - при изменении кода нужно пересобирать

🚀 Быстрый старт

Сборка для текущей ОС:

make build

Сборка для всех платформ:

make build-all

Полный релиз (сборка + пакеты):

make release

📖 Подробные инструкции

1. Установка зависимостей

Вариант А: Автоматическая установка

make install-pyinstaller

Вариант Б: Ручная установка

pip install pyinstaller
pip install -r requirements.txt

2. Сборка для Linux

На Linux системе:

make build-linux

Результат:

Файл: dist/letsencrypt-regru
Размер: ~45-55 MB
Формат: ELF 64-bit executable

Тестирование:

./dist/letsencrypt-regru --help
sudo ./dist/letsencrypt-regru --check -c /etc/letsencrypt-regru/config.json

3. Сборка для Windows

На Windows системе (PowerShell/CMD):

make build-windows

Результат:

Файл: dist/letsencrypt-regru.exe
Размер: ~40-50 MB
Формат: PE32+ executable (Windows)

Тестирование:

.\dist\letsencrypt-regru.exe --help

4. Создание пакетов для распространения

Linux пакет (tar.gz):

make package-linux

Содержимое пакета:

letsencrypt-regru - исполняемый файл
README.md - документация
systemd/ - systemd unit файлы
config.json.example - пример конфигурации

Результат: dist/letsencrypt-regru-linux-x86_64.tar.gz

Windows пакет (zip):

make package-windows

Результат: dist/letsencrypt-regru-windows-x86_64.zip

5. Полный цикл релиза

Создание релиза со всеми артефактами:

make release

Что происходит:

Очистка старых артефактов (clean-build)
Установка/обновление PyInstaller
Сборка для Linux (build-linux)
Сборка для Windows (build-windows)
Создание пакета для Linux (package-linux)
Создание пакета для Windows (package-windows)
Генерация SHA256 контрольных сумм

Результат в dist/:

letsencrypt-regru              # Linux executable
letsencrypt-regru.exe          # Windows executable
letsencrypt-regru-linux-x86_64.tar.gz
letsencrypt-regru-windows-x86_64.zip

🔄 Кросс-компиляция

⚠️ Важные замечания

Не рекомендуется:

Собирать Linux версию на Windows
Собирать Windows версию на Linux
Собирать macOS версию на других ОС

Причины:

Несовместимость системных библиотек
Разные форматы исполняемых файлов
Проблемы с путями и разделителями

🛠️ Все команды Makefile

Основные команды:

Команда	Описание
`make build`	Собрать для текущей ОС
`make build-linux`	Собрать для Linux
`make build-windows`	Собрать для Windows
`make build-all`	Собрать для всех платформ
`make package-linux`	Создать tar.gz пакет
`make package-windows`	Создать zip пакет
`make release`	Полный цикл релиза

Вспомогательные команды:

Команда	Описание
`make install-pyinstaller`	Установить PyInstaller
`make test-build`	Протестировать собранный файл
`make clean-build`	Очистить артефакты сборки
`make build-info`	Показать информацию о среде

🐛 Troubleshooting

Проблема: PyInstaller не найден

Ошибка:

make: pyinstaller: Command not found

Решение:

make install-pyinstaller
## или
pip install pyinstaller

Проблема: Импорт модулей не работает

Ошибка:

ModuleNotFoundError: No module named 'requests'

Решение:

pip install -r requirements.txt
## или добавьте в PyInstaller команду:
--hidden-import requests
--hidden-import certbot
--hidden-import cryptography

Проблема: Большой размер файла

Размер ~100+ MB вместо 40-60 MB

Причины:

Включены лишние модули
Не используется --onefile
Включены debug символы

Решение:

## Используйте флаги оптимизации:
pyinstaller --onefile \
  --strip \
  --exclude-module tkinter \
  --exclude-module matplotlib \
  letsencrypt_regru_api.py

Проблема: Certbot не работает в исполняемом файле

Ошибка:

certbot: command not found

Решение:

Certbot вызывается через subprocess и должен быть установлен в системе:

Linux:

sudo apt-get install certbot

Windows:

Не поддерживается напрямую
Используйте WSL или Docker

Проблема: Права доступа к файлам

Ошибка:

Permission denied: /etc/letsencrypt/

Решение:

## Linux/macOS
sudo ./dist/letsencrypt-regru --check

## Или установите правильные права:
sudo chmod +x ./dist/letsencrypt-regru
sudo chown root:root ./dist/letsencrypt-regru

Проблема: Медленный запуск

Первый запуск занимает 5-10 секунд

Причина: PyInstaller распаковывает файлы во временную директорию при каждом запуске.

Решение:

Это нормальное поведение для --onefile
Используйте --onedir для более быстрого запуска (но будет много файлов)
Кэшируйте временную директорию (автоматически)

Проблема: Антивирус блокирует файл

Windows Defender помечает .exe как вирус

Причины:

Самораспаковывающийся архив похож на вредоносное ПО
Отсутствие цифровой подписи
Малоизвестный исполняемый файл

Решение:

Добавьте в исключения:
- Windows Defender → Settings → Exclusions

Подпишите файл цифровой подписью:

# Требуется сертификат Code Signing
signtool sign /f cert.pfx /p password dist/letsencrypt-regru.exe

Проверьте на VirusTotal:
- Загрузите файл на virustotal.com
- Добавьте результаты в README

📊 Сравнение: Python vs Исполняемый файл

Характеристика	Python скрипт	Исполняемый файл
Размер	~50 KB	~40-60 MB
Зависимости	Требует Python + pip	Автономный
Скорость запуска	Быстро (~1 сек)	Медленно (~5-10 сек)
Обновление	Просто заменить .py	Требуется пересборка
Совместимость	Любая ОС с Python	Только для целевой ОС
Установка	Требует venv setup	Скачать и запустить
Certbot	Через subprocess	Через subprocess

🎯 Рекомендации

Используйте Python скрипт если:

✅ Python уже установлен в системе
✅ Нужны частые обновления кода
✅ Используете виртуальное окружение
✅ Работаете на серверах (production)

Используйте исполняемый файл если:

✅ Python не установлен
✅ Нужна простота развертывания
✅ Распространяете для конечных пользователей
✅ Тестирование на чистых системах

📦 Пример использования собранного файла

Linux:

## Скачать и распаковать
wget https://github.com/user/repo/releases/download/v1.0/letsencrypt-regru-linux-x86_64.tar.gz
tar -xzf letsencrypt-regru-linux-x86_64.tar.gz

## Установить
sudo mv letsencrypt-regru /usr/local/bin/
sudo chmod +x /usr/local/bin/letsencrypt-regru

## Использовать
sudo letsencrypt-regru --help
sudo letsencrypt-regru --check -c /etc/letsencrypt-regru/config.json

Windows:

## Скачать и распаковать
Invoke-WebRequest -Uri "https://github.com/user/repo/releases/download/v1.0/letsencrypt-regru-windows-x86_64.zip" -OutFile "letsencrypt-regru.zip"
Expand-Archive -Path letsencrypt-regru.zip -DestinationPath "C:\Program Files\LetsEncrypt-RegRu"

## Использовать
cd "C:\Program Files\LetsEncrypt-RegRu"
.\letsencrypt-regru.exe --help

📝 Дополнительные ресурсы

📄 Лицензия

Этот проект использует лицензию согласно основному README.md.

Автор: Фофанов Дмитрий
Дата обновления: 28.10.2025

Appendix (migrated from docs/RELEASE_GUIDE.md)

🎯 Краткое руководство: Автоматические релизы

Для GitHub

1. Создание релиза

## Создать тег
git tag -a v1.0.0 -m "Release version 1.0.0"

## Отправить тег
git push origin v1.0.0

2. Что произойдет автоматически

GitHub Actions запустит .github/workflows/build-release.yml:

✅ Сборка Linux версии (Ubuntu runner)
✅ Сборка Windows версии (Windows runner)
✅ Создание пакетов
✅ Генерация SHA256 checksums
✅ Создание GitHub Release
✅ Загрузка артефактов

3. Результат

Релиз появится на: https://github.com/USER/REPO/releases/tag/v1.0.0

Файлы:

letsencrypt-regru-linux-x86_64.tar.gz
letsencrypt-regru-linux-x86_64.tar.gz.sha256
letsencrypt-regru-windows-x86_64.zip
letsencrypt-regru-windows-x86_64.zip.sha256

Для Gitea

1. Настройка (один раз)

Включить Actions в Gitea:

Отредактируйте app.ini:

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://gitea.com

Установить Gitea Runner:

## Скачать
wget https://dl.gitea.com/act_runner/latest/act_runner-linux-amd64 -O act_runner
chmod +x act_runner

## Зарегистрировать
./act_runner register --no-interactive \
  --instance https://your-gitea.com \
  --token YOUR_RUNNER_TOKEN

## Запустить
./act_runner daemon

2. Создание релиза

## Создать тег
git tag -a v1.0.0 -m "Release version 1.0.0"

## Отправить тег
git push origin v1.0.0

3. Что произойдет

Gitea Actions запустит .gitea/workflows/release.yml:

✅ Сборка Linux версии
✅ Сборка Windows версии
✅ Создание пакетов
✅ Генерация SHA256 + MD5 checksums
✅ Создание Gitea Release
✅ Детальные release notes

4. Результат

Релиз появится на: https://your-gitea.com/USER/REPO/releases/tag/v1.0.0

🔧 Проверка перед релизом

## 1. Локальная сборка
make clean-build
make release

## 2. Тестирование
make test-build

## 3. Проверка файлов
ls -lh dist/

## 4. Если все OK - создать тег
git tag -a v1.0.0 -m "Release 1.0.0"
git push origin v1.0.0

📊 Мониторинг

GitHub:

https://github.com/USER/REPO/actions

Gitea:

https://your-gitea.com/USER/REPO/actions

🐛 Если что-то пошло не так

Удалить тег и релиз:

## Удалить локальный тег
git tag -d v1.0.0

## Удалить удаленный тег
git push --delete origin v1.0.0

## Удалить релиз вручную через веб-интерфейс

Пересоздать релиз:

## Исправить проблему
git commit -am "Fix build"

## Пересоздать тег
git tag -a v1.0.0 -m "Release 1.0.0" --force
git push origin v1.0.0 --force

📝 Semantic Versioning

## Major (несовместимые изменения)
git tag v2.0.0

## Minor (новые функции)
git tag v1.1.0

## Patch (исправления)
git tag v1.0.1

## Pre-release
git tag v1.0.0-beta.1
git tag v1.0.0-rc.1

См. также:

.gitea/README.md - Полная документация по Gitea Actions
BUILD_GUIDE.md - Руководство по сборке

21 KiB Raw Permalink Blame History Unescape Escape

Сборка и релизы

Быстрый старт

Что важно понимать

Пакеты релиза

Автоматические релизы по тегам

Ручной запуск релиза (workflow_dispatch)

Appendix (migrated from docs/QUICKSTART_BUILD.md)

🎯 Быстрый старт - Сборка исполняемых файлов

Для Linux

1. Установите зависимости

2. Клонируйте репозиторий

3. Соберите

4. Результат

5. Установите (опционально)

6. Используйте

Для Windows

1. Установите Python

2. Клонируйте репозиторий

3. Соберите

4. Результат

5. Используйте

Создание релиза для обеих платформ

Полезные команды

❓ Проблемы?

Appendix (migrated from docs/BUILD_GUIDE.md)

🔨 Руководство по сборке исполняемых файлов

📋 Содержание

✅ Преимущества исполняемых файлов

Плюсы:

Минусы:

🚀 Быстрый старт

Сборка для текущей ОС:

Сборка для всех платформ:

Полный релиз (сборка + пакеты):

📖 Подробные инструкции

1. Установка зависимостей

Вариант А: Автоматическая установка

Вариант Б: Ручная установка

2. Сборка для Linux

3. Сборка для Windows

4. Создание пакетов для распространения

Linux пакет (tar.gz):

Windows пакет (zip):

5. Полный цикл релиза

🔄 Кросс-компиляция

⚠️ Важные замечания

Рекомендации

Для Linux сборки:

Для Windows сборки:

Для обеих платформ:

🛠️ Все команды Makefile

Основные команды:

Вспомогательные команды:

🐛 Troubleshooting

Проблема: PyInstaller не найден

Проблема: Импорт модулей не работает

Проблема: Большой размер файла

Проблема: Certbot не работает в исполняемом файле

Проблема: Права доступа к файлам

Проблема: Медленный запуск

Проблема: Антивирус блокирует файл

📊 Сравнение: Python vs Исполняемый файл

🎯 Рекомендации

Используйте Python скрипт если:

Используйте исполняемый файл если:

📦 Пример использования собранного файла

Linux:

Windows:

📝 Дополнительные ресурсы

📄 Лицензия

Appendix (migrated from docs/RELEASE_GUIDE.md)

🎯 Краткое руководство: Автоматические релизы

Для GitHub

1. Создание релиза

2. Что произойдет автоматически

3. Результат

Для Gitea

1. Настройка (один раз)

Включить Actions в Gitea:

21 KiB

Raw Permalink Blame History