Руководство по установке Hearthchat

Репозиторий

Исходный код доступен по ссылке:
https://github.com/Tripod311/hearth_chat

Системные требования

Hearthchat использует mediasoup, который имеет ограниченную поддержку ARM-архитектуры.

Рекомендуемая платформа:
- x86_64 хост

Установка через docker pull

1. Создание docker-compose.yml

Создайте файл docker-compose.yml со следующим содержимым:

services:
  hearthchat:
    image: tripod311/hearthchat:latest
    container_name: hearthchat

    network_mode: host

    restart: unless-stopped

    environment:
      - HTTP_PORT=443
      - GATE_PORT=14567
      - PORT_BASE=45000
      - PORT_RANGE=999

    volumes:
      - ./data:/app/data

2. Настройка портов

Вы можете изменить порты при необходимости:

HTTP_PORT — порт для доступа к веб-интерфейсу
GATE_PORT — TCP-порт для связи между узлами
PORT_BASE / PORT_RANGE — используются для mediasoup

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

3. Запуск контейнера

Запустите приложение:

docker compose up

После запуска появится папка data — в ней хранятся все данные узла.

📦 Эту папку можно переносить между хостами (это и есть бэкап).

4. Первый вход

Откройте в браузере:

http://<адрес_хоста>:<HTTP_PORT>

Данные по умолчанию:

логин: root
пароль: root

⚠️ Рекомендуется сразу:

Создать нового пользователя
Войти под ним
Удалить пользователя root

5. Настройка TLS (рекомендуется)

Можно вручную добавить TLS-сертификаты.

Структура папок:

data/
  certificates/
    server.cert
    server.key
    server.ca (опционально)

Если сертификаты не заданы:

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

6. Фоновый режим

После первоначального запуска можно остановить контейнер и запустить его в фоне:

docker compose up -d

Примечания

Все данные хранятся в папке data
Перенос узла = копирование этой папки
Бэкап = архив data

Установка из исходников

Сборка Docker-образа из исходников

⚠️ Не рекомендуется для слабых хостов

Сборка может зависать или выполняться очень долго, так как при npm install библиотека mediasoup может запускать собственную сборку нативных зависимостей, что сильно нагружает систему.

1. Клонирование репозитория

git clone https://github.com/Tripod311/hearth_chat

Данная команда скачивает исходный код проекта с GitHub на ваш компьютер.

После выполнения появится директория hearth_chat с проектом.

2. Сборка Docker-образа

docker build -t tripod311/hearthchat:latest .

Эта команда:

собирает Docker-образ из исходников
использует текущую директорию (контекст сборки)
присваивает образу тег tripod311/hearthchat:latest

⏳ Процесс может занять значительное время в зависимости от мощности хоста.

Запуск из исходников (без Docker)

Если вы не хотите использовать Docker, приложение можно запустить напрямую как Node.js-сервис.

В этом случае:

папка data будет автоматически создана в рабочей директории проекта
все данные будут храниться локально рядом с приложением

Требования

Node.js версии 20 или выше

1. Клонирование репозитория

git clone https://github.com/Tripod311/hearth_chat

Скачивает исходный код проекта.

2. Установка зависимостей

npm install

Устанавливает все необходимые зависимости, указанные в package.json.

⚠️ На этом этапе также может происходить сборка mediasoup, что может занять время.

3. Сборка клиентской части

npx vite build

Собирает фронтенд-приложение (интерфейс) в оптимизированный production-бандл.

4. Компиляция серверной части

npx tsc

Компилирует TypeScript-код сервера в JavaScript.

Результат сборки помещается в директорию server_dist.

5. Запуск приложения

node server_dist/main.js

Запускает сервер Hearthchat.

После запуска приложение будет доступно по указанному в конфигурации порту.

Примечания

При первом запуске автоматически создаётся папка data
Все пользовательские данные, файлы и настройки хранятся в ней
Для переноса узла достаточно скопировать папку data

Локализация

Существующие локализации

По умолчанию везде доступен аглийский язык. Существующие локали можно взять из папки locales в исходниках. Чтобы установить на узел дополнительный язык, создайте в папке data папку locales и уложите туда файл с нужной локалью. Английскую можно не устанавливать, она есть по умолчанию.

Пример:

data/
  locales/
    ru.json
    fr.json

Собственные локализации

Можно легко создать локаль под свой язык, просто возьмите английскую локаль и переведите в ней все тексты. Очень быстро и удобно сделать это с помощью ИИ. Установка аналогична существующей.