docs(links): исправлены ссылки после переноса в Gitea

- Зачем:
  - старые ссылки на GitHub-репозитории возвращали 404.
- Что:
  - ссылки на учебные стенды переведены на публичные репозитории Gitea.
  - отсутствующий jupyter-spark-docker заменён официальным Jupyter Docker Stacks.
  - ссылки на каталоги SQL и данных переведены на Gitea.
- Проверка:
  - mkdocs build --strict.
  - HTTP-проверка всех изменённых URL вернула 200.

.gitea/requirements-site.txt

@@ -0,0 +1,2 @@
+mkdocs-material==9.6.14
+mkdocs-same-dir==0.1.3

.gitea/scripts/build-site.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+readonly venv_dir="/var/lib/gitea-runner/venvs/site"
+
+if [[ $# -ne 1 ]]; then
+    echo "Usage: $0 SOURCE_DIR" >&2
+    exit 2
+fi
+
+source_dir=$(realpath "$1")
+requirements_file="${source_dir}/.gitea/requirements-site.txt"
+
+if [[ ! -f $requirements_file ]]; then
+    echo "Requirements file not found: ${requirements_file}" >&2
+    exit 2
+fi
+
+mkdir -p "$(dirname "$venv_dir")"
+if [[ ! -x "${venv_dir}/bin/python" ]]; then
+    python3 -m venv "$venv_dir"
+fi
+
+"${venv_dir}/bin/python" -m pip install \
+    --disable-pip-version-check \
+    --no-input \
+    --requirement "$requirements_file"
+"${venv_dir}/bin/python" -m pip check
+cd "$source_dir"
+"${venv_dir}/bin/python" -m mkdocs build --strict

.gitea/scripts/deploy-site.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+readonly deploy_root="/srv/de-roadmap"
+readonly releases_root="${deploy_root}/releases"
+readonly keep_releases=3
+
+if [[ $# -ne 2 ]]; then
+    echo "Usage: $0 SITE_DIR COMMIT_SHA-RUN_ID" >&2
+    exit 2
+fi
+
+source_dir=$(realpath "$1")
+release_id=$2
+
+if [[ ! $release_id =~ ^[0-9a-f]{40}-[0-9]+$ ]]; then
+    echo "Invalid release id: ${release_id}" >&2
+    exit 2
+fi
+
+if [[ ! -f "${source_dir}/index.html" ]]; then
+    echo "Built site has no index.html: ${source_dir}" >&2
+    exit 2
+fi
+
+if [[ ! -d $releases_root || ! -w $releases_root || ! -w $deploy_root ]]; then
+    echo "Deployment directories are missing or not writable" >&2
+    exit 1
+fi
+
+readonly release_dir="${releases_root}/${release_id}"
+readonly staging_dir="${releases_root}/.${release_id}.tmp"
+readonly next_link="${deploy_root}/.current.${release_id}.tmp"
+
+if [[ -e $release_dir || -e $staging_dir || -e $next_link ]]; then
+    echo "Release path already exists: ${release_id}" >&2
+    exit 1
+fi
+
+cleanup() {
+    rm -rf -- "$staging_dir"
+    rm -f -- "$next_link"
+}
+trap cleanup EXIT
+
+umask 0022
+mkdir "$staging_dir"
+cp -a "${source_dir}/." "$staging_dir/"
+chmod -R u=rwX,go=rX "$staging_dir"
+mv "$staging_dir" "$release_dir"
+
+ln -s "releases/${release_id}" "$next_link"
+mv -Tf "$next_link" "${deploy_root}/current"
+
+mapfile -t old_releases < <(
+    find "$releases_root" \
+        -mindepth 1 \
+        -maxdepth 1 \
+        -type d \
+        -regextype posix-extended \
+        -regex '.*/[0-9a-f]{40}-[0-9]+' \
+        -printf '%T@ %f\n' \
+        | sort -nr \
+        | awk -v keep="$keep_releases" 'NR > keep { print $2 }'
+)
+
+for old_release in "${old_releases[@]}"; do
+    if [[ $old_release =~ ^[0-9a-f]{40}-[0-9]+$ && $old_release != "$release_id" ]]; then
+        rm -rf -- "${releases_root:?}/${old_release}"
+    fi
+done
+
+trap - EXIT
+echo "Published release ${release_id}"

.gitea/workflows/deploy-site.yml

@@ -0,0 +1,39 @@
+name: Deploy MkDocs to VPS
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: site-production
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: de-roadmap-host
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out the triggering commit
+        env:
+          COMMIT_SHA: ${{ gitea.sha }}
+          REPOSITORY_URL: ${{ gitea.server_url }}/${{ gitea.repository }}.git
+        run: |
+          set -euo pipefail
+          [[ "$COMMIT_SHA" =~ ^[0-9a-f]{40}$ ]]
+          test ! -e source
+          mkdir source
+          git -C source init .
+          git -C source remote add origin "$REPOSITORY_URL"
+          git -C source fetch --no-tags --depth=1 origin "$COMMIT_SHA"
+          test "$(git -C source rev-parse FETCH_HEAD)" = "$COMMIT_SHA"
+          git -C source -c advice.detachedHead=false checkout --detach FETCH_HEAD
+
+      - name: Build the site strictly
+        run: source/.gitea/scripts/build-site.sh source
+
+      - name: Publish the complete release atomically
+        env:
+          RELEASE_ID: ${{ gitea.sha }}-${{ gitea.run_id }}
+        run: source/.gitea/scripts/deploy-site.sh source/site "$RELEASE_ID"

AGENTS.md

@@ -4,8 +4,11 @@
 - Root `README.md` describes the learning roadmap (RU) and serves as the main page of the MkDocs site.
 - `dwh-modeling/` contains the article and demo DWH model; SQL lives in `dwh-modeling/sql` as ordered scripts `01_...sql`–`09_...sql` (07–09 are homework DDL, template and solution).
 - `postgres-bookings/` is a Dockerized PostgreSQL + demo “bookings” DB; start it first, then apply DWH scripts against the `demo` database.
-- `mkdocs.yml` — MkDocs Material config; `docs_dir: .` (repo root = site root). Excluded dirs: `project/`, `postgres-bookings/`, `.github/`, `.claude/`.
+- `mkdocs.yml` — MkDocs Material config; `docs_dir: .` (repo root = site root). Excluded dirs: `project/`, `postgres-bookings/`, `.gitea/`, `.github/`, `.claude/`.
-- `.github/workflows/deploy-site.yml` — CI/CD: push to `main` → build → deploy to GitHub Pages.
+- `.gitea/workflows/deploy-site.yml` — основной CI/CD: push в `main` → строгая
+  сборка → атомарная публикация на VPS через repository-scoped Gitea Runner.
+- `.github/workflows/deploy-site.yml` — сохранённый workflow для резервной
+  публикации на GitHub Pages; Gitea его не исполняет.
 - `project/` — PRD, ADR, and TODO.md (excluded from site). `project/TODO.md` is the prioritized project backlog: check it when planning or proposing work, and mark items done there when you complete them.
 
 ## Build, Test, and Development Commands
@@ -52,10 +55,12 @@ All `.md` files MUST render correctly on both GitHub and the MkDocs Material sit
 - Avoid: em-dash `—`, en-dash `–` — slug behavior differs between GitHub and MkDocs.
 
 ## MkDocs Site Commands
+- Initialize or update the persistent local environment:
+  `python3 -m venv "${HOME}/.cache/de-roadmap-mkdocs" && "${HOME}/.cache/de-roadmap-mkdocs/bin/python" -m pip install -r .gitea/requirements-site.txt`
 - Local preview (user starts, ask user to run via `!`):
-  `uv run --with 'mkdocs-material==9.6.14' --with 'mkdocs-same-dir==0.1.3' mkdocs serve`
+  `"${HOME}/.cache/de-roadmap-mkdocs/bin/python" -m mkdocs serve`
 - Build with strict validation (catches broken links/anchors):
-  `uv run --with 'mkdocs-material==9.6.14' --with 'mkdocs-same-dir==0.1.3' mkdocs build --strict`
+  `"${HOME}/.cache/de-roadmap-mkdocs/bin/python" -m mkdocs build --strict`
 - Visual check via Playwright (when `mkdocs serve` is running on port 8000):
   `npx playwright screenshot --viewport-size='1280,800' 'http://127.0.0.1:8000/#anchor' /path/to/screenshot.png`
   Then read the screenshot with the Read tool to inspect rendering. Use `--viewport-size='1280,2000'` for tall pages.
@@ -75,5 +80,7 @@ Pull requests should focus on one topic, include a brief context, list of change
 
 ## Security & Configuration Tips
 - Do not commit personal `.env` files or credentials; use local overrides only.
+- Gitea Runner работает в host mode: не расширяйте его scope, не добавляйте
+  пользователя `gitea-runner` в `sudo` или `docker` и не выдавайте ему запись
+  вне `/var/lib/gitea-runner` и `/srv/de-roadmap`.
 - Demo credentials and ports in `postgres-bookings` are for local training only—never reuse them in shared or production environments.
-

README.md

@@ -159,7 +159,7 @@ SQL и моделирование данных специально идут р
     - [SkillFactory: Виртуальные окружения в Python](https://blog.skillfactory.ru/venv-virtualnoe-okruzhenie-v-python/)
 - Jupyter Lab
     - [Блог Практикума: «Что такое Jupyter Notebook: как установить и открыть»](https://practicum.yandex.ru/blog/chto-takoe-jupyter-notebook/)
-    - Готовая реализация Jupyter Lab, включающая в себя Spark, в Docker: [jupyter-spark-docker](https://github.com/dementev-dev/jupyter-spark-docker)
+    - Готовый Docker-образ Jupyter Lab со Spark: [Jupyter Docker Stacks, pyspark-notebook](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html#jupyter-pyspark-notebook)
 - Pandas
     - [GeeksforGeeks: “Why Pandas is Used in Python”](https://www.geeksforgeeks.org/pandas/why-pandas-is-used-in-python/)
     - [Skillbox: «Для чего нужна библиотека Pandas»](https://skillbox.ru/media/code/rabotaem-s-pandas-osnovnye-ponyatiya-i-realnye-dannye/)
@@ -283,7 +283,7 @@ Apache Airflow — инструмент для оркестрации ETL-про
 
 Материалы:
 
-- [Учебник по Airflow](https://github.com/dementev-dev/airflow-manual)
+- [Учебник по Airflow](https://git.dementev.space/ddmitry/airflow-manual)
 
 **Когда блок Airflow считаем пройденным:**
 
@@ -313,7 +313,7 @@ Apache Airflow — инструмент для оркестрации ETL-про
 **Курс Yandex по Greenplum** — основной учебный курс, рекомендуется пройти целиком:
 
 - [Бесплатный курс Yandex Cloud по Greenplum](https://yandex.cloud/ru/training/greenplum)
-- Практику по курсу удобно делать на стенде [airflow-dwh-gp-lab](https://github.com/dementev-dev/airflow-greenplum) — `make up` поднимает рабочий Greenplum с PXF, не нужен облачный кластер.
+- Практику по курсу удобно делать на стенде [airflow-dwh-gp-lab](https://git.dementev.space/ddmitry/airflow-greenplum) — `make up` поднимает рабочий Greenplum с PXF, не нужен облачный кластер.
 - Стенд покрывает основные темы курса: типы таблиц (heap / appendonly), политики дистрибуции, сжатие, PXF, анализ планов выполнения (`EXPLAIN`).
 - Единственное ограничение: cloud-специфичные темы (тема 2 курса — развёртывание в Yandex Cloud) на локальном стенде не покрыты.
 
@@ -326,7 +326,7 @@ Apache Airflow — инструмент для оркестрации ETL-про
 ### Курсовая работа
 Курсовая работа — важный майлстоун роадмапа: ваш первый end-to-end data-проект. После неё у вас есть ключевые технические навыки для старта карьеры в Data Engineering.
 
-Курсовая выполняется на том же стенде [airflow-dwh-gp-lab](https://github.com/dementev-dev/airflow-greenplum), который вы уже использовали для практики по Greenplum.
+Курсовая выполняется на том же стенде [airflow-dwh-gp-lab](https://git.dementev.space/ddmitry/airflow-greenplum), который вы уже использовали для практики по Greenplum.
 
 **Что внутри:**
 
@@ -417,7 +417,7 @@ NiFi — визуальный конструктор потоков данных
 - [Apache NiFi с нуля за 3 часа (Youtube-плейлист)](https://youtube.com/playlist?list=PL4MpKy3QjNp_rOEEibc4Ro8UK4g8vLX6_&si=W_hidjHmBOZ_aUfS) — первые 4 видео, дальше — по желанию
 - [Лучший Гайд по Kafka для Начинающих За 1 Час (Youtube)](https://www.youtube.com/watch?v=hbseyn-CfXY)
 
-Практика — на стенде [nifi-kafka-postgres-lab](https://github.com/dementev-dev/nifi-kafka-postgres-lab) (Docker Compose с NiFi, Kafka и Postgres):
+Практика — на стенде [nifi-kafka-postgres-lab](https://git.dementev.space/ddmitry/nifi-kafka-postgres-lab) (Docker Compose с NiFi, Kafka и Postgres):
 
 - настраиваем в NiFi простой генератор данных и поток в Postgres;
 - строим поток NiFi → Kafka → NiFi → Postgres.
@@ -434,8 +434,8 @@ ClickHouse — колоночная СУБД для аналитики на бо
 
 Практика:
 
-- Упражнения курса Яндекса можно выполнять в их облаке (с оплатой за ресурсы) или бесплатно у себя — на учебном кластере [clickhouse-learning-cluster](https://github.com/dementev-dev/clickhouse-learning-cluster): 4 узла ClickHouse в Docker Compose, репликация, шардинг, балансировка через HAProxy.
+- Упражнения курса Яндекса можно выполнять в их облаке (с оплатой за ресурсы) или бесплатно у себя — на учебном кластере [clickhouse-learning-cluster](https://git.dementev.space/ddmitry/clickhouse-learning-cluster): 4 узла ClickHouse в Docker Compose, репликация, шардинг, балансировка через HAProxy.
-- Следующий шаг — стенд [clickstream-ch-kafka-superset-demo](https://github.com/dementev-dev/clickstream-ch-kafka-superset-demo), имитирующий полноценное аналитическое хранилище на ClickHouse: Kafka, Airflow, дашборды в Superset, мониторинг (Prometheus/Grafana), слои STG → ODS → DDS → DM. Внутри — собственный продвинутый курс «Кликстрим на ClickHouse» с уроками прямо на стенде.
+- Следующий шаг — стенд [clickstream-ch-kafka-superset-demo](https://git.dementev.space/ddmitry/clickstream-ch-kafka-superset-demo), имитирующий полноценное аналитическое хранилище на ClickHouse: Kafka, Airflow, дашборды в Superset, мониторинг (Prometheus/Grafana), слои STG → ODS → DDS → DM. Внутри — собственный продвинутый курс «Кликстрим на ClickHouse» с уроками прямо на стенде.
 
 ### Lakehouse (Spark, Iceberg, Trino)
 
@@ -450,7 +450,7 @@ Lakehouse — архитектурный подход, который соеди
 - Введение в тему: [«Как не утонуть в данных: выбираем между DWH, Data Lake и Lakehouse» (Habr, Arenadata)](https://habr.com/ru/companies/arenadata/articles/885722/) — что такое Lakehouse, чем он отличается от классического DWH и Data Lake и зачем появился
 - [DataLearn: «Что такое Apache Spark»](https://youtu.be/Tl9YzC-dQLI) — введение в Spark с нуля, ~40 минут
 
-Практика — курс [«Lakehouse без магии»](https://github.com/dementev-dev/mini-lakehouse-lab) на стенде mini-lakehouse-lab (Spark + Iceberg + Trino + MinIO, всё локально в Docker, без облаков и регистраций):
+Практика — курс [«Lakehouse без магии»](https://git.dementev.space/ddmitry/mini-lakehouse-lab) на стенде mini-lakehouse-lab (Spark + Iceberg + Trino + MinIO, всё локально в Docker, без облаков и регистраций):
 
 - 8 модулей на ~12–15 часов самостоятельной работы; в каждом — объяснение, демонстрация, задание и checkpoint;
 - пайплайн `raw → bronze → silver` на реальном датасете NYC Taxi;

dwh-modeling/README.md

@@ -540,7 +540,7 @@ flowchart TD
 
 ### Готовые SQL-скрипты
 
-Все необходимые скрипты для построения хранилища находятся в папке [`sql/`](https://github.com/dementev-dev/de-roadmap/tree/main/dwh-modeling/sql):
+Все необходимые скрипты для построения хранилища находятся в папке [`sql/`](https://git.dementev.space/ddmitry/de-roadmap/src/branch/main/dwh-modeling/sql):
 
 - [`01_ddl_stg-dds.sql`](sql/01_ddl_stg-dds.sql) — создание схем и таблиц (STG, ODS, DDS);
 - [`02_dml_stg-dds.sql`](sql/02_dml_stg-dds.sql) — первичная загрузка данных и демонстрация SCD2 через полный пересчёт (`full backfill`) из STG;
@@ -791,7 +791,7 @@ SELECT 'OK' WHERE EXISTS (
 
 ### Мини-датасет (для практики)
 
-Все данные для практики находятся в папке [`data/`](https://github.com/dementev-dev/de-roadmap/tree/main/dwh-modeling/data) — тренируйтесь:
+Все данные для практики находятся в папке [`data/`](https://git.dementev.space/ddmitry/de-roadmap/src/branch/main/dwh-modeling/data) — тренируйтесь:
 
 [`customers.csv`](data/customers.csv):
 ```csv
@@ -832,7 +832,7 @@ product_id,valid_from,valid_to,price
 9002,2023-01-01,,50
 ```
 
->  📂 Все SQL-скрипты для построения хранилища находятся в папке [`sql/`](https://github.com/dementev-dev/de-roadmap/tree/main/dwh-modeling/sql).
+>  📂 Все SQL-скрипты для построения хранилища находятся в папке [`sql/`](https://git.dementev.space/ddmitry/de-roadmap/src/branch/main/dwh-modeling/sql).
 
 ---
 

mkdocs.yml

@@ -3,8 +3,8 @@ site_url: https://de.dementev.space/
 site_description: "Роадмап по Data Engineering: SQL, Python, Airflow, Greenplum и далее"
 site_author: Dmitry Dementev
 
-repo_url: https://github.com/dementev-dev/de-roadmap
+repo_url: https://git.dementev.space/ddmitry/de-roadmap
-repo_name: dementev-dev/de-roadmap
+repo_name: ddmitry/de-roadmap
 
 docs_dir: .
 site_dir: site
@@ -13,6 +13,7 @@ exclude_docs: |
   project/
   postgres-bookings/
   .github/
+  .gitea/
   .claude/
   site/
   AGENTS.md
@@ -75,12 +76,12 @@ markdown_extensions:
 
 extra:
   social:
+    - icon: simple/gitea
+      link: https://git.dementev.space/ddmitry/de-roadmap
+      name: Gitea
     - icon: fontawesome/brands/telegram
       link: https://t.me/dementev_dev
       name: Написать в Telegram
-    - icon: fontawesome/brands/github
-      link: https://github.com/dementev-dev/de-roadmap
-      name: GitHub
 
 plugins:
   - same-dir

project/PRD.md

@@ -8,7 +8,10 @@
 
 ### Текущее состояние
 
-Роадмап по Data Engineering живёт как GitHub-репозиторий ([dementev-dev/de-roadmap](https://github.com/dementev-dev/de-roadmap)):
+Роадмап по Data Engineering живёт как Git-репозиторий. Основной origin
+размещён в собственной Gitea
+([ddmitry/de-roadmap](https://git.dementev.space/ddmitry/de-roadmap)), а
+GitHub Pages сохраняется как резерв после восстановления доступа к GitHub:
 
 - Основной контент — монолитный `README.md` (~700 строк) с полным учебным планом.
 - Дополнительные материалы — в подпапках (`dwh-modeling/`, `postgres-bookings/`): теория DWH-моделирования, SCD, Data Vault, домашние задания, скрипты.
@@ -74,7 +77,8 @@ GitHub README — рабочий, но не презентабельный фо
 **Деплой:**
 
 - [x] Автоматическая сборка и публикация при пуше в `main`.
-- [x] Бесплатный хостинг (GitHub Pages).
+- [x] Публикация без дополнительных расходов: собственная VPS как основной
+  контур, GitHub Pages как резерв.
 
 **Совместимость с репо:**
 
@@ -84,7 +88,8 @@ GitHub README — рабочий, но не презентабельный фо
 
 ### 4.2. Желательные (Спринт 2+)
 
-- [x] Кастомный домен: `de.dementev.space` (подключён 2026-03-27).
+- [x] Кастомный домен: `de.dementev.space` (подключён 2026-03-27, переведён на
+  VPS 2026-08-05).
 - [x] Тёмная тема (переключатель light/dark).
 - [x] Сворачиваемые блоки (`<details>`) — точечно, для подсказок/решений в домашках (2026-03-29).
 - [x] Кнопка «Написать в Telegram» — floating-кнопка + иконки в футере (2026-03-29).
@@ -158,7 +163,7 @@ GitHub README — рабочий, но не презентабельный фо
 | Кириллические якоря рендерятся по-разному | Средняя | Среднее | Тестирование конкретного генератора; при необходимости — латинские id |
 | Генератор сайта перестаёт поддерживаться | Низкая | Среднее | Контент в plain Markdown — миграция на другой генератор за день |
 | Накладные расходы на поддержку растут | Низкая | Среднее | Принцип «сайт опционален»: если мешает — удаляем конфиг, репо работает |
-| GitHub Pages ограничения (bandwidth, размер) | Очень низкая | Низкое | Для статического сайта с текстом — не актуально |
+| VPS временно недоступна | Низкая | Высокое | Опубликованный сайт не зависит от Gitea; GitHub Pages сохраняется как ручной резерв |
 
 ---
 

project/TODO.md

@@ -2,8 +2,6 @@
 
 Приоритеты: P1 — делаем в первую очередь; P2 — полезно, когда дойдут руки; P3 — идеи под вопросом.
 
-## P1
-
 ## P2
 
 - [ ] **Перенос учебника Airflow в de-roadmap.**
@@ -41,6 +39,11 @@
 
 ## Сделано
 
+- [x] **Публикация сайта перенесена на Gitea Actions и VPS** —
+  2026-08-05: настроены repository-scoped host runner, строгая сборка MkDocs,
+  атомарные релизы, nginx и TLS для `de.dementev.space`; GitHub Pages сохранён
+  как неактивный резерв.
+
 - [x] **Подраздел «Linux и терминал» в блоке базовых инструментов** —
   2026-07-12: видео-интро («Девопс на троечку», покрытие проверено по
   субтитрам) + три статьи (навигация и grep — habr, права — FirstVDS,

project/ops/gitea-vps-site/README.md

@@ -0,0 +1,283 @@
+# Эксплуатация публикации `de.dementev.space`
+
+Этот runbook реализует спецификацию
+[`2026-08-04-gitea-vps-site-publishing.md`](../../specs/2026-08-04-gitea-vps-site-publishing.md).
+Команды рассчитаны на Ubuntu 26.04 и Gitea 1.27.
+
+## Зафиксированные параметры
+
+- Gitea Runner: `2.3.0`, Linux amd64.
+- SHA256: `1e9fb1bea022fdf40993ecbc1a13e87db1bfd3d7f42666e37f15f71d840d53b3`.
+- Runner: repository-scoped, метка `de-roadmap-host:host`.
+- Пользователь сервиса: `gitea-runner`, без `sudo` и Docker.
+- Корень публикации: `/srv/de-roadmap`.
+- Хранение: текущий релиз и две предыдущие версии.
+- Окружение сборки: `/var/lib/gitea-runner/venvs/site`.
+- Публичный IPv4 VPS: `167.224.64.252`.
+
+## Предварительные условия
+
+- Есть пользователь с `sudo` и рабочий SSH-доступ к VPS.
+- Есть доступ к управлению DNS-зоной `dementev.space`.
+- В репозитории `ddmitry/de-roadmap` включены Gitea Actions.
+
+## Подготовка VPS
+
+Установить Git, HTTP-сервер, Certbot, UFW и Python venv:
+
+```bash
+sudo apt-get update
+sudo apt-get install \
+  ca-certificates \
+  certbot \
+  curl \
+  git \
+  jq \
+  nginx \
+  python3-certbot-nginx \
+  python3-venv \
+  ufw
+```
+
+Получить административный checkout, из которого устанавливаются tracked-файлы:
+
+```bash
+git clone https://git.dementev.space/ddmitry/de-roadmap.git
+cd de-roadmap
+```
+
+Создать пользователя и каталоги:
+
+```bash
+sudo useradd \
+  --system \
+  --home-dir /var/lib/gitea-runner \
+  --create-home \
+  --shell /usr/sbin/nologin \
+  gitea-runner
+sudo install -d -o gitea-runner -g gitea-runner -m 0755 \
+  /var/lib/gitea-runner/workspaces \
+  /srv/de-roadmap \
+  /srv/de-roadmap/releases
+sudo install -d -o root -g root -m 0755 /etc/gitea-runner
+```
+
+Скачать runner во временный каталог, сверить checksum и установить root-owned
+бинарник в `/usr/local/bin/gitea-runner`:
+
+```bash
+runner_tmp_dir=$(mktemp -d /tmp/de-roadmap-runner.XXXXXX)
+curl -fsSLo "${runner_tmp_dir}/gitea-runner" \
+  https://dl.gitea.com/gitea-runner/2.3.0/gitea-runner-2.3.0-linux-amd64
+printf '%s  %s\n' \
+  '1e9fb1bea022fdf40993ecbc1a13e87db1bfd3d7f42666e37f15f71d840d53b3' \
+  "${runner_tmp_dir}/gitea-runner" \
+  | sha256sum --check
+sudo install -o root -g root -m 0755 \
+  "${runner_tmp_dir}/gitea-runner" /usr/local/bin/gitea-runner
+rm "${runner_tmp_dir}/gitea-runner"
+rmdir "$runner_tmp_dir"
+```
+
+Из корня репозитория установить конфигурацию и unit:
+
+```bash
+sudo install -o root -g root -m 0644 \
+  project/ops/gitea-vps-site/gitea-runner.yaml \
+  /etc/gitea-runner/config.yaml
+sudo install -o root -g root -m 0644 \
+  project/ops/gitea-vps-site/gitea-runner.service \
+  /etc/systemd/system/gitea-runner.service
+sudo systemd-analyze verify /etc/systemd/system/gitea-runner.service
+```
+
+## Регистрация runner
+
+Repository registration token получают в Gitea:
+`ddmitry/de-roadmap` → Settings → Actions → Runners. Токен не сохраняют в Git
+или shell history. Временный файл с токеном создают с владельцем
+`gitea-runner:gitea-runner` и режимом `0600`. После регистрации файл
+`/var/lib/gitea-runner/.runner` должен принадлежать тому же пользователю и
+иметь режим `0600`.
+
+Token-file должен содержать ровно 40 символов без завершающего перевода строки.
+При извлечении JSON-ответа через `jq` использовать `jq --join-output '.token'`,
+а не `jq --raw-output`, который добавляет newline.
+
+```bash
+sudo -u gitea-runner \
+  /usr/local/bin/gitea-runner \
+  --config /etc/gitea-runner/config.yaml \
+  register \
+  --no-interactive \
+  --instance https://git.dementev.space \
+  --token-file /var/lib/gitea-runner/.registration-token \
+  --name de-roadmap-vps
+sudo rm /var/lib/gitea-runner/.registration-token
+sudo chmod 0600 /var/lib/gitea-runner/.runner
+sudo systemctl daemon-reload
+sudo systemctl enable --now gitea-runner
+systemctl is-enabled gitea-runner
+systemctl is-active gitea-runner
+```
+
+Временный файл с токеном удаляют сразу после успешной регистрации. В Gitea на
+странице Settings → Actions → Runners runner `de-roadmap-vps` должен перейти в
+состояние online и показывать метку `de-roadmap-host`.
+
+## Nginx и первичная публикация
+
+Из корня репозитория установить bootstrap-конфигурацию nginx, создать ссылку,
+отключить стандартный сайт Ubuntu и только затем перечитать проверенную
+конфигурацию:
+
+```bash
+sudo install -o root -g root -m 0644 \
+  project/ops/gitea-vps-site/nginx.conf \
+  /etc/nginx/sites-available/de-roadmap
+sudo ln -s \
+  /etc/nginx/sites-available/de-roadmap \
+  /etc/nginx/sites-enabled/de-roadmap
+sudo unlink /etc/nginx/sites-enabled/default
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+Первый server block в `nginx.conf` возвращает `404` для неизвестных HTTP Host,
+не раскрывает версию nginx и отклоняет TLS handshake для IP или неизвестного
+SNI. Поэтому сертификат `de.dementev.space` не выдаётся при обращении к VPS по
+IP. Если проверка конфигурации не прошла, отключить новый virtual host,
+восстановить стандартный сайт и перечитать проверенную конфигурацию:
+
+```bash
+sudo unlink /etc/nginx/sites-enabled/de-roadmap
+sudo ln -s \
+  /etc/nginx/sites-available/default \
+  /etc/nginx/sites-enabled/default
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+Файл `project/ops/gitea-vps-site/nginx.conf` предназначен только для запуска до
+выпуска сертификата. После выпуска сертификата Certbot изменяет установленный
+virtual host. Повторная установка bootstrap-файла поверх рабочего конфига
+удалит TLS-директивы.
+
+## Окружение сборки
+
+Скрипт `.gitea/scripts/build-site.sh` создаёт persistent venv при первом запуске
+и переиспользует его в следующих сборках. `pip install` выполняется каждый раз,
+чтобы применить изменения `.gitea/requirements-site.txt`, но уже установленные
+версии пакетов не переустанавливаются.
+
+## Первый деплой
+
+В Gitea открыть Actions → Deploy MkDocs to VPS, выбрать ветку `main` и нажать
+Run workflow. Job `deploy` должен завершиться успешно. Проверить опубликованный
+release и локальную выдачу nginx до переключения DNS:
+
+```bash
+readlink -f /srv/de-roadmap/current
+curl --fail --header 'Host: de.dementev.space' http://127.0.0.1/
+```
+
+Затем разрешить SSH, HTTP и HTTPS в UFW. Если SSH работает не на стандартном
+порту `22`, сначала разрешить фактический порт вместо профиля `OpenSSH`:
+
+```bash
+sudo ufw default deny incoming
+sudo ufw default allow outgoing
+sudo ufw allow OpenSSH
+sudo ufw allow 'Nginx Full'
+sudo ufw enable
+sudo ufw status verbose
+```
+
+Ожидается политика `deny (incoming)` и разрешения только для SSH, `80/tcp` и
+`443/tcp`.
+
+## DNS и TLS
+
+1. Уменьшить TTL записи `de.dementev.space`.
+2. Направить `A` на VPS; удалить или корректно направить `AAAA`.
+3. Убедиться, что сайт доступен извне по HTTP:
+
+    ```bash
+    curl --fail --head http://de.dementev.space/
+    ```
+
+4. Выпустить сертификат и включить перенаправление HTTP на HTTPS:
+
+    ```bash
+    sudo certbot --nginx \
+      --non-interactive \
+      --agree-tos \
+      --email me@dementev.space \
+      --redirect \
+      -d de.dementev.space
+    ```
+
+5. В созданном Certbot HTTP-блоке для `de.dementev.space` добавить
+   `server_tokens off;`, затем проверить и перечитать конфигурацию:
+
+    ```bash
+    sudoedit /etc/nginx/sites-available/de-roadmap
+    sudo nginx -t
+    sudo systemctl reload nginx
+    ```
+
+6. Проверить перенаправление, HTTPS, сертификат и автоматическое продление:
+
+    ```bash
+    curl --head http://de.dementev.space/
+    curl --fail --head https://de.dementev.space/
+    ! curl --insecure --head https://167.224.64.252/
+    sudo certbot certificates
+    systemctl is-enabled certbot.timer
+    systemctl is-active certbot.timer
+    ```
+
+   Ожидаются `301 Moved Permanently`, затем `200 OK`, отказ TLS по IP,
+   действующий сертификат и состояния таймера `enabled` и `active`.
+
+7. Вернуть обычный DNS TTL.
+
+## Проверка и откат
+
+Активная версия определяется ссылкой `/srv/de-roadmap/current`. Для ручного
+отката сначала выбрать точный release id из сохранённых каталогов, затем создать
+временную ссылку и атомарно заменить `current`:
+
+```bash
+find /srv/de-roadmap/releases \
+  -mindepth 1 \
+  -maxdepth 1 \
+  -type d \
+  -printf '%f\n' \
+  | sort
+
+rollback_release='<COMMIT_SHA>-<RUN_ID>'
+rollback_link='/srv/de-roadmap/.current.rollback'
+[[ "$rollback_release" =~ ^[0-9a-f]{40}-[0-9]+$ ]]
+sudo test -d "/srv/de-roadmap/releases/${rollback_release}"
+sudo test ! -e "$rollback_link"
+sudo -u gitea-runner \
+  ln -s "releases/${rollback_release}" "$rollback_link"
+sudo -u gitea-runner \
+  mv -Tf "$rollback_link" /srv/de-roadmap/current
+readlink -f /srv/de-roadmap/current
+curl --fail --head https://de.dementev.space/
+```
+
+Откат не удаляет более новые releases. Перед их ручным удалением всегда
+проверять результат `readlink -f /srv/de-roadmap/current`.
+
+Диагностика:
+
+```bash
+sudo systemctl status gitea-runner
+sudo journalctl -u gitea-runner
+sudo nginx -t
+readlink -f /srv/de-roadmap/current
+curl --fail --head https://de.dementev.space/
+```

project/ops/gitea-vps-site/gitea-runner.service

@@ -0,0 +1,45 @@
+[Unit]
+Description=Gitea Actions runner for de-roadmap
+Documentation=https://docs.gitea.com/usage/actions
+Wants=network-online.target
+After=network-online.target
+
+[Service]
+Type=simple
+User=gitea-runner
+Group=gitea-runner
+WorkingDirectory=/var/lib/gitea-runner
+ExecStart=/usr/local/bin/gitea-runner daemon --config /etc/gitea-runner/config.yaml
+Restart=always
+RestartSec=10s
+TimeoutStopSec=45s
+KillMode=mixed
+
+Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+
+UMask=0022
+NoNewPrivileges=true
+PrivateDevices=true
+PrivateTmp=true
+ProtectClock=true
+ProtectControlGroups=true
+ProtectHome=true
+ProtectHostname=true
+ProtectKernelLogs=true
+ProtectKernelModules=true
+ProtectKernelTunables=true
+ProtectSystem=strict
+ReadWritePaths=/var/lib/gitea-runner /srv/de-roadmap
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
+RestrictRealtime=true
+RestrictSUIDSGID=true
+LockPersonality=true
+CapabilityBoundingSet=
+SystemCallArchitectures=native
+
+MemoryMax=1G
+CPUQuota=100%
+TasksMax=128
+
+[Install]
+WantedBy=multi-user.target

project/ops/gitea-vps-site/gitea-runner.yaml

@@ -0,0 +1,37 @@
+log:
+  level: info
+
+runner:
+  file: /var/lib/gitea-runner/.runner
+  capacity: 1
+  timeout: 15m
+  shutdown_timeout: 30s
+  insecure: false
+  fetch_timeout: 5s
+  fetch_interval: 2s
+  fetch_interval_max: 10s
+  workdir_cleanup_age: 24h
+  idle_cleanup_interval: 10m
+  labels:
+    - "de-roadmap-host:host"
+  allocate_pty: false
+
+cache:
+  enabled: false
+
+container:
+  valid_volumes: []
+  docker_host: "-"
+  require_docker: false
+
+host:
+  workdir_parent: /var/lib/gitea-runner/workspaces
+
+health_check:
+  enabled: true
+  min_free_disk_space_mb: 1024
+  interval: 30s
+  timeout: 10s
+
+metrics:
+  enabled: false

project/ops/gitea-vps-site/nginx.conf

@@ -0,0 +1,34 @@
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    listen 443 ssl default_server;
+    listen [::]:443 ssl default_server;
+
+    server_name _;
+    server_tokens off;
+    ssl_reject_handshake on;
+
+    return 404;
+}
+
+server {
+    listen 80;
+    listen [::]:80;
+
+    server_name de.dementev.space;
+    root /srv/de-roadmap/current;
+    index index.html;
+    charset utf-8;
+    server_tokens off;
+
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+
+    location / {
+        try_files $uri $uri/ =404;
+    }
+
+    location ~ /\. {
+        deny all;
+    }
+}

project/specs/2026-08-04-gitea-vps-site-publishing.md

@@ -1,7 +1,9 @@
 # Публикация сайта через Gitea Actions и VPS
 
-Статус: согласовано 2026-08-04; механизм синхронизации GitHub-резерва
+Статус: реализовано 2026-08-05; механизм синхронизации GitHub-резерва требует
-требует отдельного решения после восстановления доступа к GitHub.
+отдельного решения после восстановления доступа к GitHub. Инструкции по
+восстановлению и эксплуатации находятся в
+[`project/ops/gitea-vps-site/README.md`](../ops/gitea-vps-site/README.md).
 
 ## Проблема
 
@@ -26,7 +28,7 @@
 - Изменение существующих файлов в `.github/workflows/`.
 - Добавление динамического приложения, авторизации или серверной базы данных.
 
-## Текущее состояние
+## Исходное состояние на 2026-08-04
 
 - MkDocs Material собирает статический каталог `site/`; `site_url` уже равен `https://de.dementev.space/`.
 - Публичный репозиторий `ddmitry/de-roadmap` в Gitea является текущим `origin`.