- Astro 36.7%
- CSS 25.8%
- TypeScript 18.6%
- Shell 16.2%
- JavaScript 2.7%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .forgejo | ||
| public | ||
| scripts | ||
| src | ||
| .gitignore | ||
| astro.config.mjs | ||
| package.json | ||
| pnpm-lock.yaml | ||
| README.md | ||
| RUNBOOK.md | ||
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:
nix eval→services.json(в контейнереnixos/nix, ~2 секунды с учётом pull);- клонирует репозиторий сайта с бот-токеном;
- коммитит
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.
Разница только в том, кто автор пуша — бот, а не вы.
Событие для обновления сайта нужно в любом случае. Вариантов ровно три:
- пуш в репозиторий сайта (бот) — самый простой, событие уже нативное;
repository_dispatchчерез API Forgejo — пуш не нужен, но тогда сайт должен сам сходить за json (нужен read-токен и шаг скачивания);- опрос по
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:
pnpm install --frozen-lockfile && pnpm build;rsync dist/ → clegg:/var/www/services/releases/<sha>/;ln -sfnпереключаетcurrent— атомарно, без окна простоя;- старые релизы (кроме 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 ....