Если вы хотите взаимодействовать со своими читателями с помощью комментариев на своем веб-сайте, это руководство поможет вам начать.

Вы также получите другие преимущества, такие как:

Построение сообщества. Ваши читатели будут знать друг друга, а вы узнаете о них больше.
Повышение SEO от читателей, которые предоставляют дополнительный контент, отзывы, вопросы и свое мнение.
Лучший пользовательский опыт, так как читателям не нужно покидать ваш сайт, если они хотят связаться с вами.

Один из недостатков всего этого? Ну, это может быть сложно настроить.

В документации Remark42 рекомендуется использовать поддомен, который выглядит следующим образом:

www.remark42.yourwebsite.com

Но я собираюсь развернуть Remark42 в качестве пути на своем веб-сайте, например:

www.yourwebsite.com/remark

Вот официальная документация по настройке Remark42 без поддомена.

У каждого из них есть плюсы и минусы, но я не буду вдаваться в подробности.

В этом уроке я проведу вас через его настройку.

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

Возможно, вы искали систему комментариев и наткнулись на несколько, таких как Disqus и Giscus.

Они оба предлагают исключительные услуги, но один платный, а другой позволяет только аутентификацию через Github.

Я хотел что-то бесплатное и с надежным потоком аутентификации.

Какой инструмент выбрать?

Ремарка 42.

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

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

Вот неполный список других интересных функций, которые Remarks предоставляет «из коробки»:

Многоуровневые вложенные комментарии как с древовидными, так и с простыми презентациями
Импорт из Disqus и WordPress
Поддержка Markdown с удобной панелью инструментов форматирования
Модераторы могут удалять комментарии и блокировать пользователей
Система голосования, закрепления и верификации
и многое другое…

Посетите их веб-сайт для получения дополнительной информации или посетите их демоверсию, чтобы получить представление об этом.

Требования к оборудованию

Я предполагаю, что у вас уже установлен VPS, Coolify и домен, как www.yourwebsite.com уже настроен.

Ну, а если у вас нет ничего из этого? Обратитесь к моему руководству!

Самостоятельный хостинг вашего сайта с помощью Coolify v4: пошаговое руководство

Remark42 не требует много ресурсов. По моей оценке, минимальные характеристики, которые вам понадобятся вместе с Coolify, следующие:

2 ядра процессора
4 ГБ оперативной памяти
1 ТБ+ хранилища

Если вы планируете развертывать несколько приложений и служб, вам потребуется больше мощности.

В настоящее время я работаю на 4 процессоре/8 ГБ оперативной памяти со 160 ГБ хранилища на Hetzner, где у меня развернуто около 10 приложений.

Требования к программному обеспечению

Для того, чтобы это работало с любым фронтенд-проектом, нам понадобится Docker.

Самый простой способ установить Docker — скачать Docker Desktop.

Он поставляется в комплекте со всем необходимым для начала работы.

Есть 3 файла, которые мы собираемся создать, чтобы все это работало:

Файл Dockerfile
docker-compose.yaml
nginx.conf

Вот Dockerfile инструкции, которые подскажут Docker, как создать наш образ фронтенда.

Он docker-compose.yaml сообщает Docker, как находить или создавать образы, а затем запускать их в контейнерах.

Это nginx.conf файл конфигурации для нашего сервера обратного прокси, чтобы он мог правильно обслуживать файлы из наших контейнеров.

Связывает их вместе Docker, где он создает и развертывает фронтенд, Remark42 и сервер nginx.

Замечание по подготовке42

Выбор аутентификации

Прежде чем мы настроим Remark42, вам нужно выяснить, как вы хотите, чтобы ваши читатели авторизовались, чтобы оставлять комментарии.

Что бы вы хотели, чтобы сделали читатели?

Публиковать анонимно?
Входите в систему с помощью электронной почты и пароля?
Используете поставщиков OAuth, таких как Google?

Что ж, на самом деле вы можете использовать комбинацию этих вариантов.

Лично я выбрал несколько провайдеров OAuth, потому что они более безопасны, предотвращают спам и конфиденциальная информация не хранится.

Если вы хотите использовать поставщики OAuth, вам придется настроить их заранее, чтобы получить идентификаторы и секреты клиента для дальнейшего использования в этом руководстве.

Я не буду показывать вам, как это сделать, но я обнаружил, что Github — самый простой для начала работы.

Обратитесь к этой документации по получению идентификаторов и секретов клиентов OAuth для распространенных поставщиков.

Для каждого выбранного вами провайдера OAuth вы должны предоставить правильный обратный вызов, чтобы Remark42 мог правильно обрабатывать запросы от провайдеров.

URL обратного вызова выглядит следующим образом:

https://yourwebsite.com/remark/auth/<provider>/callback

Для локального развития используйте:

http://127.0.0.1:<port>/remark/auth/<provider>/callback

** ПРИМЕЧАНИЕ ** Не все провайдеры разрешают разработку localhost.

Уведомления

Remark42 может включить уведомления, когда кто-то оставляет комментарий.

Доступные варианты: Slack, электронная почта и Telegram.

Я выбрал Telegram, потому что его невероятно легко настроить.

Для получения ключа API вам нужен аккаунт в Telegram.

Как только вы это сделаете, вам нужно будет отправить сообщение @BotFather по адресу /newbot

Следуйте инструкциям, чтобы присвоить боту отображаемое имя и имя пользователя.

Я выбрал billyle.dev comments в качестве отображаемого имени и имя пользователя . billyle_dev_comments_bot

Вы получите токен API там, где красная полоса находится на изображении выше.

Мы будем использовать это значение в нашем .env файле.

Нам нужно создать приватный канал и пригласить бота в наш приватный канал.

Все созданные каналы по умолчанию являются приватными.

Чтобы создать канал, следуйте этим инструкциям для вашего устройства.

Теперь пришло время получить идентификатор канала, что немного сложно.

Я обнаружил, что самый простой способ — войти в Telegram через веб-браузер, чтобы получить его.

После получения идентификатора канала вам нужно будет добавить к нему префикс -100.

В приведенном выше примере фактический идентификатор канала выглядит следующим образом: -1002460468573.

Теперь, чтобы пригласить нашего бота на наш канал, выполните следующие действия:

Зайдите в свой личный канал, найдите кнопку «Админы» и нажмите на «Добавить админа».
Нажмите на иконку аватара канала.
Найдите кнопку «Администраторы» и нажмите ее.
Нажмите на кнопку «Добавить администратора».
Введите имя пользователя вашего бота и нажмите на него
Настройте разрешения для бота, чтобы у него были только привилегии «Публикация».
Нажмите «Готово»

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

Разобравшись с этим, теперь мы можем перейти к аспекту программирования в этом уроке.

Настройка проекта

Наш следующий шаг — переход в корень вашего фронтенд-проекта.

Например, файловая структура этого сайта выглядит следующим образом:

.
├── astro.config.ts
├── dist
├── docker-compose.yaml
├── Dockerfile
├── nginx.conf
├── node_modules
├── package.json
├── pnpm-lock.yaml
├── postcss.config.mjs
├── public
├── README.md
├── remark-plugins
├── src
├── tailwind.config.mjs
├── tsconfig.json
└── unstage-drafts.ts

Это простой проект, но независимо от того, насколько сложен ваш фронтенд, в идеале его основные концепции должны работать одинаково.

Перейдем к .env файлу.

.env файл

Создайте .env файл в корне вашего фронтенд-проекта.

В этом файле добавьте все переменные окружения для методов аутентификации.

PUBLIC_REMARK_URL=https://yourwebsite.com/remark
PUBLIC_SITE=my_website
REMARK_SECRET=superSecret123
REMARK_ALLOWED_HOSTS="'self',https://yourwebsite.com"
ADMIN_SHARED_ID=
AUTH_GOOGLE_CID=
AUTH_GOOGLE_CSEC=
AUTH_GITHUB_CID=
AUTH_GITHUB_CSEC=
TELEGRAM_TOKEN=
NOTIFY_TELEGRAM_CHAN=

И PUBLIC_REMARK_URL REMARK_SECRET требуются в соответствии с Remark42.

URL-адрес публичного замечания должен выглядеть следующим образомhttp://yourwebsite.com/remark.

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

Это PUBLIC_SITE поле пользовательского имени. По умолчанию так и есть, remark но я выбрал осмысленное имя, например billyle_dev

Будет REMARK_ALLOWED_HOSTS значением "self,https://yourwebsite.com".

Это обеспечит нам дополнительную безопасность, так как только запросы с нашего домена имеют право на выполнение запросов.

Добавьте оставшееся значение ключа для выбранных вами провайдеров аутентификации и конфигурации Telegram.

Разобравшись с этим, давайте создадим наш Dockerfileдомен .

Файл Dockerfile

Если вы используете Astro, этот пример Dockerfile подойдет вам с небольшими настройками.

Но если вы используете другой фреймворк, такой как NextJS, Solid, Vue и т. д., вам придется искать, как создать для них Dockerfile.

В корне создайте файл.

touch Dockerfile

А затем скопируйте это, если вы используете Astro.

# syntax=docker/dockerfile:1

ARG NODE_VERSION=lts
ARG PNPM_VERSION=9.12.3

FROM node:${NODE_VERSION}-alpine AS base
WORKDIR /usr/src/app
RUN --mount=type=cache,target=/root/.npm \
    npm install -g pnpm@${PNPM_VERSION}
COPY package.json pnpm-lock.yaml ./

FROM base AS prod-deps
RUN pnpm install --prod --frozen-lockfile

FROM base AS build-deps
RUN pnpm install --frozen-lockfile

FROM build-deps AS build
ARG PUBLIC_REMARK_URL
ARG PUBLIC_SITE
ENV PUBLIC_REMARK_URL=${PUBLIC_REMARK_URL}
ENV PUBLIC_SITE=${PUBLIC_SITE}
COPY . .
RUN --mount=type=cache,target=/usr/src/app/node_modules/.astro \
    --mount=type=cache,target=/root/.astro/cache,sharing=locked \
    mkdir -p node_modules/.astro && \
    pnpm run build

FROM base AS runtime
COPY --from=prod-deps /usr/src/app/node_modules ./node_modules
COPY --from=build /usr/src/app/dist ./dist

FROM nginx:stable-alpine3.17 AS final
COPY nginx.conf /etc/nginx/nginx.conf
COPY --from=build /usr/src/app/dist /usr/share/nginx/html
EXPOSE 4321

Я не буду вдаваться в подробности, но в этом Dockerfile случае мы создаем многоступенчатый процесс, чтобы воспользоваться преимуществами кэширования Docker.

Мы хотим делать наши сборки быстрыми, поэтому мы разделяем разные части процесса сборки.

Например, на первом шаге мы скопировали package.json файлы andpnpm-lock.yaml, и они кэшируются Docker.

Затем, на следующих нескольких шагах, Docker запускается только pnpm install в том случае, если два файла изменились, в противном случае мы обращаемся к тому, что было кэшировано.

Если вы хотите узнать об этом больше, ознакомьтесь с документацией по кэшу сборки Docker .

Еще одно важное замечание — это то, как мы создаем переменные среды.

Значения ARG будут переданы в our Dockerfile и установить нашу ENV переменную из Docker Compose.

В свою очередь, он ENV будет использоваться в процессе сборки для фронтенда.

Как только это будет завершено, мы перейдем к созданию docker-compose.yaml.

docker-compose.yaml

В корне создайте файл из терминала.

touch docker-compose.yaml

Скопируйте код ниже. Внесите коррективы в проект как в сервис, так frontend и remark в сервис.

services:
  frontend:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        PUBLIC_REMARK_URL: ${PUBLIC_REMARK_URL}
        PUBLIC_SITE: ${PUBLIC_SITE}
    container_name: "frontend"
    ports:
      - "4321:4321"
    expose:
      - "4321"
    networks:
      - app
    environment:
      - PUBLIC_REMARK_URL=${PUBLIC_REMARK_URL}
      - PUBLIC_SITE=${PUBLIC_SITE}
    env_file:
      - .env
  remark42:
    image: umputun/remark42:latest
    container_name: remark42
    hostname: remark42
    restart: always
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"
    ports:
      - "8081:8080"
    networks:
      - app
    environment:
      - REMARK_URL=${PUBLIC_REMARK_URL}
      - SITE=${PUBLIC_SITE}
      - SECRET=${REMARK_SECRET}
      - ADMIN_SHARED_ID=${ADMIN_SHARED_ID}
      - AUTH_GOOGLE_CID=${AUTH_GOOGLE_CID}
      - AUTH_GOOGLE_CSEC=${AUTH_GOOGLE_CSEC}
      - AUTH_GITHUB_CID=${AUTH_GITHUB_CID}
      - AUTH_GITHUB_CSEC=${AUTH_GITHUB_CSEC}
      - AUTH_TELEGRAM=true
      - NOTIFY_ADMINS=telegram
      - TELEGRAM_TOKEN=${TELEGRAM_TOKEN}
      - NOTIFY_TELEGRAM_CHAN=${NOTIFY_TELEGRAM_CHAN}
      - ALLOWED_HOSTS=${REMARK_ALLOWED_HOSTS}
    env_file:
      - .env
    volumes:
      - remark42:/srv/var

networks:
  app:

volumes:
  remark42:

Обратитесь к конфигурации серверной части, чтобы просмотреть все доступные варианты.

В этом файле происходит довольно много вещей.

Мы создали два сервиса, frontend каждый remarkсо своими конфигурациями.
Мы извлекаем переменные среды из .env env_file.
Мы сопоставили порты обоих сервисов для связи с хостом.
Мы создали сеть под названием app «Эти два контейнера» могут взаимодействовать друг с другом.
Наконец, мы создали том для примечаний для хранения наших комментариев.

Следует отметить, что наш frontend сервис использует время build: . , в то время как наш сервис этого не делает.remark

Конфигурация NGINX

Теперь создайте еще один файл в корне вашего проекта с именем nginx.conf

touch nginx.conf

Вот шаблон, который вы можете использовать для проекта Astro.

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

worker_processes  1;

events {
  worker_connections  1024;
}

http {
  server {
    listen 4321;
    server_name _;

    root   /usr/share/nginx/html;
    index  index.html index.htm;
    include /etc/nginx/mime.types;

    gzip on;
    gzip_comp_level 5;
    gzip_min_length 1024;
    gzip_proxied any;
    gzip_types text/plain text/css application/json application/javascript application/x-javascript text/xml application/xml application/xml+rss text/javascript application/font-woff application/font-woff2 image/svg+xml;

    client_max_body_size 10M;
    client_body_timeout 12;
    client_header_timeout 12;
    send_timeout 10;
    keepalive_timeout 65;

    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options DENY;
    add_header X-XSS-Protection "1; mode=block";

    error_page 404 /404.html;
    location = /404.html {
      root /usr/share/nginx/html;
      internal;
    }

    error_page 500 502 503 504 /50x.html;
    location = /50x.html {
        root /usr/share/nginx/html;
        internal;
    }

    location / {
      try_files $uri $uri/index.html =404;
    }

    location /remark/ {
      rewrite /remark/(.*) /\ break;
      proxy_pass http://remark42:8080/;
      proxy_set_header Host $http_host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
    }
  }
}

В этой конфигурации мы настраиваем наш сервер на прослушивание порта 4321 и ответ на каждый путь.

Тот Dockerfile , который мы создали ранее, скопирует этот конфиг в контейнер nginx.

Важная деталь заключается в /remark/ пути, по которому будут проксироваться все запросы к https://yourwebsite.com:4321/remark/* сервису Remark42 на порт 8080, который мы создали в docker-compose.yaml файле.

Позже мы добавим еще несколько настроек для отключения демо-страницы.

Настройка фронтенда

Все, что нам теперь нужно сделать, это указать, где Remark42 будет отображаться на фронтенде.

Нам нужно будет создать глобальную переменную remark_config и передать ей некоторые конфигурации, а когда страница загрузится, мы вызовем функцию для отправки запроса к нашему remark42 серверу.

Я создал компонент для этого в Astro и вы можете сделать что-то подобное в React или ванильном JS.

Создайте файл с именем, Remark42.astro если вы используете Astro, и используйте следующее:

<script>
  var remark_config = {
    host: import.meta.env.PUBLIC_REMARK_URL,
    site_id: import.meta.env.PUBLIC_SITE,
    components: ["embed"],
    theme: window.localStorage.getItem("theme") ?? "dark",
    locale: "en",
    show_email_subscription: true,
    show_rss_subscription: false,
    no_footer: true,
    __colors__: {},
  };

  window.remark_config = remark_config;

  function createRemark42Script(components: string[], doc: Document) {
    for (let i = 0; i < components.length; i++) {
      let scriptEl: HTMLScriptElement = doc.createElement("script");
      let ext = ".js";
      let headOrBodyEl = doc.head || doc.body;

      if ("noModule" in scriptEl && !scriptEl.noModule) {
        scriptEl.type = "module";
        ext = ".mjs";
      } else {
        scriptEl.async = true;
        scriptEl.defer = true;
      }

      scriptEl.src = `${window.remark_config.host}/web/${components[i]}${ext}`;
      headOrBodyEl.appendChild(scriptEl);
    }
  }
  if ("remark_config" in window) {
    window.addEventListener("DOMContentLoaded", () => {
      createRemark42Script(
        window.remark_config.components || ["embed"],
        document,
      );
    });
  }
</script>

<section id="remark42"></section>
<noscript
  >Please enable JavaScript to view the comments powered by Remark42.</noscript
>

В нашем теге script требуется remark_config атрибут и remark_url site_id.

Эти значения будут поступать из нашего .env файла, который мы передали как ARG в frontend сервис в Docker Compose.

Она remark_config будет прикреплена к окну в качестве глобальной переменной, которая будет использоваться . createRemark42Script

Чтобы найти больше вариантов конфигурации, обратитесь к руководству по фронтенду.

Наконец, нам нужен элемент HTML для рендеринга нашего компонента Remark42.

Добавьте контейнер с идентификатором и remark42 поместите его там, где вы хотите его отрисовывать.

<section id="remark42"></section>

При желании добавьте <noscript> тег. Это необязательно.

Созданы 3 файла — Dockerfile, docker-compose.yaml, и nginx.conf — . Давайте попробуем запустить его прямо сейчас!

Запуск сервисов

Итак, теперь мы наконец-то здесь!

Теперь мы можем проверить, работает ли что-то.

В терминале выполните следующую команду:

docker compose up --build

Вы должны увидеть извлечение и сборку образов Docker следующим образом:

Надеюсь, все соберется без ошибок, и теперь вы должны увидеть два работающих сервера — frontend и remark42.

Чтобы проверить, перейдите во внешний интерфейс, указав, 127.0.0.1:$PORT/remark/web где $PORT — номер вашего порта.

Вы должны видеть запросы, поступающие к вашему фронтенду, и отмечать сервисы, подобные приведенным выше.

Если у вас возникли проблемы, остановите контейнеры и выполните отладку, нажмите CTRL + C, а затем:

docker compose down

Если все хорошо, вы должны быть на странице примечаний к демо, размещенной на вашем сайте!

Стать администратором

Решите, какой поставщик аутентификации войдет в систему как администратор, так как вы будете использовать идентификатор этого пользователя.

remark42 sigin with different auth providers

Если вы правильно настроили OAuth, вы сможете войти в систему и вернуться на свой сайт.

Я использую Github для входа в систему как администратор, и после завершения входа я вижу свой аватар.

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

Скопируйте id и вставьте его в поле .env для ADMIN_SHARED_ID= поля.

Перезапустите контейнеры с помощью клавиш CTRL + C, а затем выполните:

docker compose down

Запустите docker compose up --build и обновите страницу, и теперь вы должны увидеть опцию «Показать настройки», которая означает, что вы являетесь администратором.

Если все в порядке, объедините его с основной веткой и отправьте в удаленный репозиторий.

Ваш существующий интерфейс не должен быть затронут, так как мы не изменили «Build Pack» в Coolify, и ваша существующая сборка Coolify должна продолжать выполнять команду сборки, как и раньше.

Развертывание на Coolify

Конфигурация проекта

Перейдите к экземпляру администратора Coolify и перейдите к месту, где развернут ваш проект фронтенда.

Измените опцию «Build Pack» на «Docker Compose».

Coolify загрузит ваш docker-compose.yaml файл, и теперь вы должны увидеть два поля с Domains названиями, относящимися к нашим услугам.

Добавьте номер порта вашего фронтенд-приложения из вашего nginx.conf домена в ваш домен.

https://yourwebsite.com:4321

configuring project for docker compose in coolify

И нажмите на «Сохранить», чтобы конфигурации загрузились.

Вы должны увидеть в сгенерированных метках Coolify порты обратного прокси:

Переменные среды

Перейдите на вкладку «Переменные среды», нажмите на «Просмотр разработчика», а затем введите все значения из вашего .env

Нажмите кнопку Сохранить, чтобы сохранить значения.

Развёртывание

Давайте развернем наше приложение с нашей новой конфигурацией. Нажмите на кнопку «Redeploy» и наблюдайте за сборкой.

Это может занять некоторое время в зависимости от размера вашего проекта, так как это будет первый раз, когда Docker Compose создает ваши образы.

Как только это будет завершено, вы должны увидеть, что ваши службы запущены и запущен «Новый контейнер».

Перейдите на свой веб-сайт, где будет отображаться Remark42, и попробуйте войти в систему с той же авторизацией, которую вы использовали для администрирования.

Надеемся, что все работает и теперь вы можете оставить комментарий и увидеть уведомление от Telegram.

Сводка

Поздравляю! Вы наконец-то установили Remark42 на свой сайт без поддомена.

Мы прошли большой путь, но, надеюсь, оно того стоило.

Теперь ваши читатели могут оставлять комментарии!

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

После того, как мы закодировали все необходимые биты, мы узнали, как развернуть их на Coolify.

Если у вас возникли проблемы с этим руководством, пожалуйста, оставьте комментарий или, если вы нашли это полезным, оставьте спасибо!

До новых встреч, удачного кодирования!

https://billyle.dev/posts/comments-for-all-add-remark42-with-coolify-to-your-website

Комментарии для всех: Добавьте Remark42 с Coolify на свой сайт