Obsidian LiveSync - совместная работа над проектной документацией

Предыстория

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

• Discord и Telegram для коммуникации.
• Git-сервер на базе Gitea. Ссылка на наш Git-сервер.
• Mattermost для ведения и распределения задач.
• Wiki-платформа для документации.

С последней возникли и в дальнейшем могли возникать небольшие трудности. Дело в том, что нередко во время созвона, общими усилиями, создаются проектные документы (составление плана действий или разработка архитектуры приложения). Когда всё это происходит на Wiki, тот, кто заполняет документ в процессе обсуждения, должен регулярно его сохранять, а все остальные участники обновлять страницу, что безусловно, доставляет неудобств и провоцирует как дискоммуникацию, так и потерю "нити обсуждения" у отдельных участников.

Тогда мы задумались, какой инструмент поможет обеспечить доступность файлов "почти в реальном времени" (говорить об "абсолютной трансляции изменений" мы не можем, потому что учитываем задержки, которые составляют не больше 3-х секунд).

Obsidian как среда ведения документации

Нам пришла, на первый взгляд, весьма странная идея:

"Что будет, если сделать среду ведения документации в Obsidian?".

В Obsidian из коробки есть инструмент синхронизации между устройствами, но он платный. Однако, у Obsidian обширное сообщество разработчиков и там есть плагины практически на любые случаи жизни. Так оказалось и в этой ситуации.

Был найден плагин Self-hosted LiveSync, представляющий собой реализацию "живой синхронизации" между несколькими устройствами.

Репозиторий плагина на GitHub.

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

Изучение документации по плагину

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

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

У проекта странный и я бы даже сказал, неудобный способ развёртывания. Всё дело в том, что запустить БД в Docker не составляет труда, а вот запуск миграции и получение URL-настройки требуют дополнительных действий, которые хоть и описаны в документации, но автор исходил из своего стека и окружения, и унифицировал по минимуму.

Что за CouchDB?

CouchDB — это документно-ориентированная база данных с открытым исходным кодом, которая хранит данные в формате JSON. Она разработана для обеспечения высокой доступности, отказоустойчивости и горизонтальной масштабируемости. CouchDB использует подход к обработке данных под названием "Multi-Version Concurrency Control" (MVCC), который позволяет обрабатывать данные без блокировки, что особенно полезно для распределённых систем.

Официальный сайт.

Основные особенности CouchDB:

1. Хранение данных в виде JSON-документов. Это упрощает работу с неструктурированными данными.
2. Запросы с использованием MapReduce. CouchDB позволяет использовать MapReduce для индексации и обработки данных.
3. Replication (Репликация). CouchDB поддерживает двустороннюю репликацию данных, что идеально подходит для распределённых систем, которые должны синхронизироваться между несколькими узлами или устройствами.
4. RESTful API. Взаимодействие с CouchDB происходит через HTTP-запросы, что упрощает интеграцию с веб-приложениями и различными сервисами.
5. Конфликтное управление. CouchDB умеет обнаруживать и разрешать конфликты при репликации данных, позволяя пользователям решать, как обрабатывать такие конфликты.

Запуск сервера БД

Для работы сервера БД потребуется три вещи:

1. Создать docker-compose.yaml, описывающий сервис с БД, а также сервис с Caddy (вместо Кадди можно выбрать что-то другое, например, nginx или traefic)
2. Доменное имя, чтобы была поддержка HTTPS-протокола.
3. Запустить всё это =)

Что такое Caddy, можно прочитать в посте "Веб-сервер Caddy - Альтернатива NGINX и Apache".

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

mkdir obsidian-livesync

docker-compose.yaml

Создадим и откроем файл:

touch docker-compose.yaml
nano docker-compose.yaml

Далее прописываем два сервиса (или просто копируем и вставляем):

services:
  caddy:
    image: caddy:latest
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./caddy/caddy_data:/data
      - ./caddy/caddy_config:/config

  couchdb:
    image: couchdb:latest
    container_name: obsidian-livesync
    environment:
      - COUCHDB_USER=bduser
      - COUCHDB_PASSWORD=bdpassword
    volumes:
      - ./ols/couchdb-data:/opt/couchdb/data
      - ./ols/couchdb-etc:/opt/couchdb/etc/local.d
    restart: unless-stopped

На что, стоит обратить внимание в конфигурации:

• В параметре environment, передаются переменные окружения, а именно логин и пароль пользователя БД. Запомните их, они понадобятся дальше.
• В параметре volumes, передаются пути для локального сохранения конфигураций и файлов, чтобы их не потерять при перезапуске контейнеров.
• В сервисе couchdb мы не указываем порты, поскольку подключаться к нему будем через веб-сервер Caddy.
• В параметре container_name у сервиса couchdb, прописано имя контейнера, вы можете поменять на другое. Оно нам понадобится дальше.

Сохраняем и выходим нажав CTRL+S и CTRL+X.

Caddyfile

Далее нужно создать файл конфигурации для Caddy.

Создадим и откроем файл:

touch Caddyfile
nano Caddyfile

Прописываем простейшую конфигурацию для проксирования запросов от веб-сервера к сервису с БД:

ols.napkinworkshop.ru {
    tls info@pressanybutton.ru

    log {
        output stdout
        level WARN
    }

    reverse_proxy couchdb:5984
}

На, что стоит обратить внимание:

• ols.napkinworkshop.ru - доменное имя, в нашем случае это домен третьего уровня.
• tls info@pressanybutton.ru - адрес электронной почты для получения SSL-сертификата.
• reverse_proxy couchdb:5984 - имя хоста и порт для проксирования. Тут ничего не меняем.

Сохраняем и выходим нажав CTRL+S и CTRL+X.

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

Подготовились, теперь пора запустить сервер БД.

Для запуска выполняем команду:

docker compose up -d

Выполним команду docker ps -a убеждаемся, что оба контейнера поднялись.

Добавление в контейнер зависимостей

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

Для запуска одного из скриптов, требуется JavaScript интерпретатор. Разработчиком подразумевается использование Deno, его и установим внутри контейнера.

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

docker exec -it obsidian-livesync bash

Где obsidian-livesync - это имя контейнера с CouchDB.

Оказавшись внутри, перед тем как установить Deno, нам не хватает пакета unzip, которого нет в контейнере по умолчанию. Для установки выполним следующие команды:

apt update
apt install unzip

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

curl -fsSL https://deno.land/install.sh | sh

Во время установки нас спросят, хотим ли мы добавить Deno в переменную окружения PATH? Соглашаемся отправив Y.

На следующем вопросе просто нажимаем Enter. Готово, но чтобы всё заработало, надо перезапустить сеанс оболочки bash. Для этого надо выйти из контейнера и зайти снова.

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

exit

docker exec -it obsidian-livesync bash

Инициализация БД

После всех приготовлений, осталось совсем чуть-чуть.

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

export hostname=localhost:5984
export username=bduser
export password=bdpassword

Они необходимы для корректной работы скрипта.
Первую переменную hostname не меняем, а в username и password вписываем данные указанные в docker-compose.yaml.

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

curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | bash

В итоге должны получить вывод как на скриншоте:

Генерация URI для настройки плагина

Инициализация выполнена, теперь надо сгенерировать URI, по которому плагин сможет подключиться к серверу.

Для этого нам снова придётся добавить несколько переменных окружения:

export hostname=https://ols.napkinworkshop.ru
export database=napkinworkshop
export passphrase=werysecretpassphrase

В этот раз, значением переменной hostname, указываем доменное имя с подключенным SSL-сертификатом.
Далее указываем ещё две переменные: имя базы данных и секретную фразу.

После этого выполняем команду, которая запустит TypeScript-код:

deno run -A https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/flyio/generate_setupuri.ts

В результате выполнения, получим очень длинный URI и секретную фразу для его расшифровки.

obsidian://setuplivesync?settings=%25a0cd2e1c9d6b14fbaac2b5e00100000009099c60c89628c3da5ff34a5b8872331FyDWDq0XBGbh7xhYWOCx9crFSssKVazwi1CtGRwsYKudKbipbZBKO5oXGn4oJWFJPwk2LvVmjgxTBgh5fCrqjD0QBGsb%2B2jRGYV46YpvzFdKGh%2BdOoJRubwCdTcK2psk7mCxHr2fgi81nVwCLB785qLpNckSNBHjYOS1HaDbNdBIqI3ynkN3SPjVgGtfT69T4XPQYoSCljxr0W9VUYqBw7KO%2BsfoZj7mp5m2V%2FGOW5cvJeM2dFt1cwoYKYqo9%2BScnBS7uH%2F5hiITmppte09%2BmhSWSwj2hq%2BxasILl65sVdQ1PNBezrQb7wERujY8Osa84gr0eHWWJiwkMi9ZXrWWy1Rakne4loCgSA6CT7fPxG6uLrRd3HZ9FkNX81tq8XZ4QU2BzjU5DM0klskxckAivlWe1oAFfl2WnDGKl5iEMqHju%2BRXYQYRBz%2FaJpjBR52yqnt%2F5bvXsI9koNpxyxF4i6GFaWk8y7rScv%2BFZ8kOQzAcPlJXAojzjd8biGAOwcXqTRhI85Csj4sGl34b1AM12f65CoGH0gntsoZ5aO87XaD1RQd2M%2FqgsrZ3lvOkM7paW38lpIuIkeYUbW9oFCC8e2kKU8lmYxeCDujriQ8rQNHLaOVt%2Beju%2FyUBLQt8U0YVlIfRv%2F%2BNzni%2B2l8X2H0IBDc3FVIDlJ8OHeI6xHm7E1xsgc2M4%2BNeUD5dJq9

Your passphrase of Setup-URI is:  long-dust

Сохраните их! Они показываются только раз.

Поздравляю. На этом настройка серверной части завершена. Можно переходить к клиентской.

Настройка клиента

Откроем Obsidian. На этом моменте нужно сделать выбор:

• Использовать имеющееся хранилище (vault) для синхронизации
• Создать новое.

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

Создание нового хранилища

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

Для того, чтобы создать новое хранилище, в нижнем-левом углу нажимаем по открытому и нажимаем "Manage vaults...".

В открывшемся окне выбираем "Создать новое хранилище":

Вводим название хранилища и его расположение на диске:

И нажимаем "Создать".

Готово. Новое хранилище создано.

Установка плагина

Открываем настройки Obsidian (шестерёнка в левом нижнем углу).

Переходим в раздел "Сторонние плагины" и нажимаем кнопку "Включите плагины сообщества".

Далее, в пункте "Плагины сообщества" нажимаем кнопку "Обзор".

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

В карточке плагина нажимаем кнопку "Установить", после того, как плагин установится, нажимаем кнопку "Включить".

Настройка плагина

После включения плагина, отобразится окно настройки. Нажимаем на первую кнопку "Use the copied setup URI".

В отобразившемся окне вводим сгенерированный URI и нажимаем "Ok".
Напомню, что у меня он выглядит так:

obsidian://setuplivesync?settings=%25a0cd2e1c9d6b14fbaac2b5e00100000009099c60c89628c3da5ff34a5b8872331FyDWDq0XBGbh7xhYWOCx9crFSssKVazwi1CtGRwsYKudKbipbZBKO5oXGn4oJWFJPwk2LvVmjgxTBgh5fCrqjD0QBGsb%2B2jRGYV46YpvzFdKGh%2BdOoJRubwCdTcK2psk7mCxHr2fgi81nVwCLB785qLpNckSNBHjYOS1HaDbNdBIqI3ynkN3SPjVgGtfT69T4XPQYoSCljxr0W9VUYqBw7KO%2BsfoZj7mp5m2V%2FGOW5cvJeM2dFt1cwoYKYqo9%2BScnBS7uH%2F5hiITmppte09%2BmhSWSwj2hq%2BxasILl65sVdQ1PNBezrQb7wERujY8Osa84gr0eHWWJiwkMi9ZXrWWy1Rakne4loCgSA6CT7fPxG6uLrRd3HZ9FkNX81tq8XZ4QU2BzjU5DM0klskxckAivlWe1oAFfl2WnDGKl5iEMqHju%2BRXYQYRBz%2FaJpjBR52yqnt%2F5bvXsI9koNpxyxF4i6GFaWk8y7rScv%2BFZ8kOQzAcPlJXAojzjd8biGAOwcXqTRhI85Csj4sGl34b1AM12f65CoGH0gntsoZ5aO87XaD1RQd2M%2FqgsrZ3lvOkM7paW38lpIuIkeYUbW9oFCC8e2kKU8lmYxeCDujriQ8rQNHLaOVt%2Beju%2FyUBLQt8U0YVlIfRv%2F%2BNzni%2B2l8X2H0IBDc3FVIDlJ8OHeI6xHm7E1xsgc2M4%2BNeUD5dJq9

На следующем окне вводим секретную фразу и нажимаем "Ok".
В моём случае, это long-dust.

Далее будет ряд окон с выбором:

В первом окне указываем "Yes", это разрешение на импорт конфигурации.

Во втором окне выбираем "Set it up as secondary or subsequent device", указывая, что это устройство будет использоваться как вторичное (первичным выступает сервер БД).

После этого пройдут процессы по настройке. Когда она завершится, отобразится последнее диалоговое окно, спрашивающее о разрешении включить в синхронизацию скрытые файлы (конфигурации хранилища). Нажимаем на кнопку с таймером "keep them disabled". Если включить синхронизацию скрытых файлов, то конфигурации хранилища на разных устройствах будут конфликтовать и будут часто выходить сообщения с выбором варианта для мерджа.

Выбор способа синхронизации

Плагин обладает множеством настроек (мы и сами ещё не все попробовали) но есть один параметр который улучшил наше взаимодействие.

Откройте настройки Obsidian и выберите настройки плагина.

Переходим в пятую вкладку "Sync Settings".

Тут нас интересует пункт "Sync Mode". По умолчанию он установлен в режим "Periodic and On Events", нас такой вариант не устроил и мы выбрали пункт "LiveSync".
Также, отключили параметр "Batch database update".

Заключение

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

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

Вот как мы организовали домашнюю страницу нашей рабочей документации: