Как устроен SlopHub

Сайт живёт на своём сервере одним docker-стеком: лендинг, бэкенд с публичным API, вики и аналитика. Ни GitHub Pages, ни внешних сервисов — всё своё.

Что где

              прокси (80/443, сертификаты)
                        │
   slophub.ru ──────────┼──→ лендинг на Astro (SSR)
   api.slophub.ru ──────┼──→ бэкенд на Go
   wiki.slophub.ru ─────┼──→ Wiki.js
   stats.slophub.ru ────┴──→ Umami
                        │
                    PostgreSQL

Перед всем стоит Nginx Proxy Manager: он держит домены, выписывает сертификаты Let’s Encrypt и раскидывает запросы по контейнерам. Настраивается кликами в вебе — конфиги nginx руками никто не пишет.

Лендинг

Astro, но не статика: страницы рендерятся на запрос и берут содержимое из API. Это принципиально. Раньше сайт собирался из markdown-файлов, и любая новая запись означала пересборку и деплой. Теперь запись появляется в базе — и она сразу на сайте.

Чтобы не ходить в базу на каждый запрос, ответы API кэшируются в памяти на минуту. Публикация сбрасывает кэш сама, так что задержки нет и здесь.

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

Бэкенд

Go, PostgreSQL, никакой ORM. Весь контент — записи шести типов: лента изменений, новости, ссылки, мемы, идеи и статьи. У них общая основа и небольшие различия, поэтому в базе это одна таблица, а не шесть.

Интересное здесь — порядок работы. Сначала пишется спецификация OpenAPI, и уже из неё генерируются типы и маршруты сервера. Она же проверяет входящие запросы. Спецификация физически не может разойтись с кодом: если убрать поле из одной, не соберётся другое. Для публичного API это главное свойство.

Публичное API

Весь контент сайта можно забрать без регистрации и показать где угодно. Документация с возможностью «попробовать» — на api.slophub.ru/docs, машиночитаемая спецификация — /openapi.yaml, по ней генерируется клиент на любом языке.

Самое простое — забрать последние записи:

curl 'https://api.slophub.ru/api/v1/entries?limit=5'

Фильтры комбинируются: kind=news,link вернёт только новости и ссылки, tag=агенты — записи с тегом, q=промпты — полнотекстовый поиск с русской морфологией, так что «промптов» найдёт «промпты».

Постраничность курсорная, а не по номеру страницы: контент постоянно добавляется, и смещения начинают врать — пока листаешь, вторая страница съезжает. Берите next_cursor из ответа и передавайте обратно.

Лимит — 60 запросов в минуту с адреса. Нужно больше, попросите ключ: с ним 600. Доступа он не открывает, читать может кто угодно.

Вики

Wiki.js на отдельном домене. Это не прихоть: вики правится прямо в браузере, без git и пул-реквестов, — а это важно, когда материал пишут не только разработчики. Заметные правки со временем начнут сами попадать в ленту изменений.

Как добавить материал

Через телеграм-бота: пересылаете ему сообщение, он спрашивает, куда это положить, и запись появляется на сайте. Заголовок со страницы по ссылке, первоисточник у пересланного и теги из хештегов он разбирает сам.

Аккаунт заводится по приглашению, паролей нет — вход на сайт тоже через бота, одноразовым кодом. От роли зависит, публикуется запись сразу или уходит на одобрение.

Подробности — в статье «Как присылать материалы».

Чего пока нет: правки опубликованного и длинных статей — для них нужна админка, она следующая в работе.

Что дальше

Ближайшее — сквозной поиск по сайту и вики, автоматическая подтяжка правок вики в ленту и картинки для соцсетей. Всё это лежит в идеях, статус меняется по мере готовности.