No description
  • Astro 36.7%
  • CSS 25.8%
  • TypeScript 18.6%
  • Shell 16.2%
  • JavaScript 2.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
crsito-bot 2754141607
All checks were successful
build & deploy / deploy (push) Successful in 1m5s
chore: sync services.json from crsito@2f14a5d
2026-11-07 19:18:53 +00:00
.forgejo test 2026-11-05 23:17:54 +03:00
public test 2026-11-05 21:10:21 +03:00
scripts test 2026-11-05 23:17:54 +03:00
src chore: sync services.json from crsito@2f14a5d 2026-11-07 19:18:53 +00:00
.gitignore test 2026-11-05 21:10:21 +03:00
astro.config.mjs test 2026-11-05 21:10:21 +03:00
package.json test 2026-11-05 21:10:21 +03:00
pnpm-lock.yaml test 2026-11-05 21:10:21 +03:00
README.md test 2026-11-05 21:10:21 +03:00
RUNBOOK.md test 2026-11-05 23:17:54 +03:00

uuve.org/services — сайт, сгенерированный из services.nix

Статический сайт на Astro, который целиком собирается из реестра сервисов NixOS-флейка. Добавил сервис в services.nix → через минуту он на сайте.

┌──────────────────────────────┐         ┌───────────────────────────┐
│  crsito (NixOS flake)        │         │  crsito-web (этот репо)   │
│                              │         │                           │
│  services.nix  ──────────────┼──┐      │  src/data/services.json   │
│  ├─ lms     (модуль NixOS)   │  │      │           │               │
│  ├─ mitra   (модуль NixOS)   │  │      │           ▼               │
│  └─ ...                      │  │      │  astro build → dist/       │
│                              │  │      │           │               │
│  services-export.nix         │  │      │           ▼               │
│  (allowlist полей, 25 мс)    │  │      │  rsync → clegg:/var/www/  │
│           │                  │  │      │                           │
│           ▼                  │  └─────▶│  .forgejo/workflows/      │
│  nix eval → services.json    │  push   │    deploy.yml             │
└──────────────────────────────┘         └───────────────────────────┘
        .forgejo/workflows/export-services.yml

Почему так, а не через nixos-rebuild

Сборка сайта и сборка NixOS — это две независимые вещи. nix eval / nix build только вычисляют выражения, они не трогают систему, не требуют nixos-rebuild, не требуют root и не перезагружают ничего.

Проверить на своём репозитории:

$ time nix eval --impure --json --expr '(import ./services-export.nix { })' > /dev/null
real    0m0,026s

26 миллисекунд, без сети, без nixpkgs, без сборки.

Отдельно: генерировать services.json внутри nixos-rebuild (activation-скриптом в /var/www) — плохая идея. Активация пишет в императивный путь вне /nix/store, поэтому:

  • сайт обновляется только когда вы деплоите систему (то есть та же медленная петля, от которой вы хотели уйти);
  • состояние не откатывается вместе с деплоем — magicRollback вернёт систему, а /var/www/services.json останется новым;
  • нельзя посмотреть, «что было на сайте» на конкретном коммите.

Правильная модель: services.json — чистая функция от git-коммита, она пересчитывается в CI на каждый пуш.

Миф: «JSON можно получить только после ребилда»

Экспорту нужны ровно три файла и nix eval. Ни flake.nix, ни .git, ни nixpkgs, ни сети, ни собранной системы:

$ mkdir /tmp/bare && cd /tmp/bare
$ cp .../crsito/{services.nix,servers-list.nix,services-export.nix} .
$ nix eval --impure --json --expr '(import ./services-export.nix { })'
получено сервисов: 14
real    0m0,034s

nixos-rebuild читает тот же файл, но он тут вообще ни при чём: он нужен, чтобы применить конфигурацию к машине, а не чтобы посмотреть в неё. Поэтому экспорт можно делать в любой момент — на ноутбуке, в CI, в контейнере nixos/nix, в pre-commit-хуке.

SSG, SSR и зачем тут Astro

Astro — это в первую очередь SSG-фреймворк, а не SSR. Его смысл не в серверном рендере, а в контентном пайплайне:

  • content collections — типизированный фронтматтер, опечатка в .md роняет сборку, а не рендерит битую страницу;
  • markdown/MDX из коробки, подсветка кода, RSS, sitemap;
  • islands — интерактив (фильтр по тегам, поиск) без превращения сайта в SPA;
  • ноль JS по умолчанию → страница весит килобайты.

Если бы нужен был SSR — брали бы Next/Nuxt/SvelteKit. Astro выбирают ровно за SSG.

SSG ≠ «сайт застыл». Обновление — это git push → CI → новый билд, ровно то, что у вас уже работает для .md. Второй источник данных (services.json) ничего в этой схеме не меняет: он просто ещё один файл в репозитории к моменту astro build.

SSR нужен только там, где данные меняются без пуша: сессии, лайки, live-статус, персонализация. Каталог сервисов меняется только коммитом — серверный рендер тут не даёт ничего, кроме процесса, который надо держать, и потери кешируемости.

И это не «или-или»: в Astro можно оставить сайт статикой и включить SSR точечно для одного роута (Astro 5+):

---
export const prerender = false; // только эта страница рендерится на сервере
---

Например, каталог — статика, а /status — SSR с живой проверкой портов. Сменить режим потом = поменять адаптер, а не переписать сайт.

Даже если бы services.json появлялся только после деплоя системы, SSG остался бы правильным выбором: в deploy.nix (или в CI после деплоя) ставится один workflow_dispatch в репозиторий сайта — и он пересобирается. SSR всё равно не нужен.

Варианты доставки services.json

как плюсы минусы
A. Экспорт в CI crsito, пуш в репо сайта (реализовано) CI crsito → nix eval → бот-коммит в crsito-web → CI сайта CI сайта не знает про Nix; виден дифф; можно править руками нужен бот-токен, два workflow
B. Один workflow в репо сайта CI сайта клонирует crsito (read-токен) → nix eval → astro build ничего не меняется в crsito nix в CI сайта, два контейнера (nix + node)
C. Pre-commit хук в crsito хук пересчитывает services.json рядом с services.nix нет CI вообще можно забыть хук, нет гарантии
D. Runtime fetch из браузера fetch('/services.json') на клиенте всегда свежо SEO/вес/лишний запрос — для каталога не стоит

Рекомендация — A: сайт остаётся чисто-node проектом, который собирается где угодно, а Nix-специфика заперта в NixOS-репозитории.

Как устроен экспорт

src/data/services.json — не ручной файл, а результат:

$ nix eval --impure --json --expr '(import ./services-export.nix { includeInternal = true; })'

Ключевые моменты services-export.nix:

  • impl и proxy-impl не попадают в JSON. Это NixOS-модули (функции), builtins.toJSON на них падает. Мы их просто не форсим — ленивость Nix означает, что сломанный import ./services/foo.nix на экспорт не влияет.
  • Белый список полей (publicFields), а не removeAttrs. Если завтра в сервис добавят password или token, он не утечёт на публичный сайт.
  • Сервисы без domain (server-proxy и т.п.) помечаются public = false и на сайт по умолчанию не попадают.

Пример одной записи:

{
  "name": "mitra",
  "domain": "mitra.uuve.org",
  "url": "https://mitra.uuve.org",
  "server": "clegg",
  "proxy": "nginx",
  "http-port": 8786,
  "http-host": "127.0.0.1",
  "public": true,
  "instance_title": "UUVE"
}

Локальная разработка

$ export SERVICES_REPO=/путь/к/репо/crsito
$ pnpm install
$ pnpm sync     # services.nix -> src/data/services.json (~30 мс)
$ pnpm dev      # localhost:4321

pnpm sync нужен только когда меняется реестр; сам JSON лежит в репозитории, поэтому сборка сайта не требует Nix (важно, если потом захочется Cloudflare Pages / Netlify).

CI/CD

Две независимые оси времени — не путать:

событие что происходит время
пуш .md в репо сайта astro build → rsync ~30 с
пуш в services.nix nix eval → json в репо сайта → astro build → rsync ~1 мин
nixos-rebuild / deploy-rs применяется конфигурация системы минуты

Сайт не ждёт третью строку. Он реагирует на свой пуш, а json появляется из первого workflow.

1. Репозиторий crsito — экспорт

.forgejo/workflows/export-services.yml срабатывает на пуш, который трогает services.nix / servers-list.nix / services-export.nix:

  1. nix eval → services.json (в контейнере nixos/nix, ~2 секунды с учётом pull);
  2. клонирует репозиторий сайта с бот-токеном;
  3. коммитит src/data/services.json, если он изменился.

Нужен секрет WEBSITE_TOKEN (Forgejo → Settings → Applications → Generate token, права write:repository).

Так как шаг 3 — обычный пуш в репозиторий сайта, дальше автоматически запускается второй workflow. Итого от git push в services.nix до живого сайта — около минуты, без единого nixos-rebuild.

Как один репозиторий пишет в другой

Никто ничего не «опрашивает» и не «видит чужие пуши». Событийная цепочка такая:

ты: git push crsito
 └─ Forgejo: push в crsito          → export-services.yml
     └─ внутри job'а: git clone crsito-web + commit + git push
         └─ Forgejo: push в crsito-web (от бота)   ← такой же обычный пуш
             └─ deploy.yml: pnpm build → rsync → clegg

Репозиторий сайта не знает про services.nix. Он реагирует на свой on: push. Разница только в том, кто автор пуша — бот, а не вы.

Событие для обновления сайта нужно в любом случае. Вариантов ровно три:

  1. пуш в репозиторий сайта (бот) — самый простой, событие уже нативное;
  2. repository_dispatch через API Forgejo — пуш не нужен, но тогда сайт должен сам сходить за json (нужен read-токен и шаг скачивания);
  3. опрос по schedule — cron каждые N минут проверяет чужой репозиторий. Это и есть тот самый polling, которого лучше избегать: задержка + лишние запуски.

Чем авторизоваться

Деплой-ключ (рекомендую) — доступ ровно к одному репозиторию, только на запись:

$ ssh-keygen -t ed25519 -N '' -f crsito-bot
# публичную часть: crsito-web → Settings → Deploy keys → Add, [x] Write access
# приватную: crsito → Settings → Actions → Secrets → WEBSITE_SSH_KEY
- name: Обновить репозиторий сайта
  env:
    SSH_KEY: ${{ secrets.WEBSITE_SSH_KEY }}
  run: |
    install -m 700 -d ~/.ssh
    printf '%s\n' "$SSH_KEY" > ~/.ssh/id_ed25519
    export GIT_SSH_COMMAND="ssh -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=accept-new"
    git clone --depth 1 git@git.uuve.org:luc_ren/crsito-web.git site
    # ... commit + push

Личный токен бота — проще, но токен видит все репозитории бота:

$ git clone "https://oauth2:${TOKEN}@git.uuve.org/luc_ren/crsito-web.git" site

Секреты кладутся в Settings → Actions → Secrets репозитория crsito, в yaml попадает только ${{ secrets.… }}.

Чтобы не было бесконечной петли

  • if git diff --quiet; then exit 0; fi — если json не изменился, бот не коммитит и второй CI не запускается;
  • в deploy.yml у репозитория сайта фильтр paths, чтобы пуш одного json не тянул лишнего;
  • не используйте встроенный GITHUB_TOKEN для пуша между репозиториями: в GitHub-совместимых CI пуш таким токеном часто не порождает новый запуск (защита от рекурсии). С деплой-ключом или токеном бота пуш — обычный, и workflow сайта гарантированно стартует;
  • если на main включена защита ветки — разрешите боту пуш (или пусть бот пушит в main в обход правил).

Проверено локально

Демо из двух bare-репозиториев с post-receive вместо раннеров — _demo/chain в этом воркспейсе:

$ git push origin main
remote: [CI crsito] ▶ push получен → export-services.yml
remote: [CI crsito]   nix eval → 15 сервисов
remote: remote:    [CI crsito-web] ▶ push получен → deploy.yml: pnpm build && rsync → clegg
remote: remote:    [CI crsito-web] ✓ сайт пересобран
remote: [CI crsito] ✓ json запушен в crsito-web ботом

$ git log origin/main            # в репозитории сайта
  0afa5cd crsito-bot: chore: sync services.json
  5a68de8 crsito-bot: chore: sync services.json
  69f1462 init: init

Пуш, который реестр не меняет, обрывает цепочку на первом шаге:

remote: [CI crsito]   json не изменился → выходим, второй CI не запускаем

2. Репозиторий crsito-web — сборка и деплой

.forgejo/workflows/deploy.yml:

  1. pnpm install --frozen-lockfile && pnpm build;
  2. rsync dist/ → clegg:/var/www/services/releases/<sha>/;
  3. ln -sfn переключает current — атомарно, без окна простоя;
  4. старые релизы (кроме 5) удаляются → откат = ln -sfn <старый sha> current.

Нужны секреты DEPLOY_SSH_KEY (приватный ключ, которому разрешён вход на luc_ren@clegg.uuve.org:1004) и, если хотите, DEPLOY_HOST.

Альтернатива rsync — не выкладывать вообще, а сделать сайт flake-инпутом NixOS-конфига и отдавать root = "${site.packages.x86_64-linux.default}". Плюс: атомарность и откат даёт сам Nix. Минус: каждое изменение сайта = nixos-rebuild (та самая медленная петля). Для контента, который меняется часто, — не стоит.

Nginx на clegg

Добавить в NixOS-конфиг (это декларативно, как и остальные ваши vhost'ы):

services.nginx.virtualHosts."services.uuve.org" = {
  forceSSL = true;
  enableACME = true;
  root = "/var/www/services/current";
  locations."/".tryFiles = "$uri $uri/ $uri/index.html =404";
};

Если хочется под uuve.org/services/, то в astro.config.mjs нужен base: '/services' (и тогда все ссылки в шаблонах — через import.meta.env.BASE_URL).

Что ещё стоит сделать

  • Описания и теги. Сейчас на странице сервиса показываются технические поля, потому что в реестре больше ничего нет. Добавьте в services.nix обычные поля и допишите их в publicFields:

    {
      name = "forgejo";
      domain = "git.uuve.org";
      description = "Git-хостинг агентства";
      tags = [ "git" "ci" ];
      # ...
    }
    
  • Проверка в CI, что JSON валиден. Уже есть в export-services.yml (пустой/битый экспорт валит job, а не публикует пустой сайт).

  • Контент, который нельзя вывести из Nix (лонгриды, скриншоты) — держите в src/content/ и мержите по имени сервиса, а из services.json берите только факты.

  • nix build .#services-json. Если хочется совсем по-нixовски, добавьте в modules/ файл:

    { ... }: {
      perSystem = { pkgs, ... }: {
        packages.services-json = pkgs.writeText "services.json"
          (builtins.toJSON (import ../../../services-export.nix { includeInternal = true; }));
      };
    }
    

    Тогда CI делает nix build .#services-json && cp result/services.json ....