$Id: README 27 2019-07-23 11:26:37Z abalama $
App::DistSync v1.04 and later
This document written in Windows-1251 charset
=============================================

КОРОТКО О ПРОЕКТЕ
-----------------

App::DistSync - готовое решение для синхронизации двух и более WEB ресурсов
между собой. Данный проект отлично зарекомендовал себя в синхронизации
сайтов на которых размещаются дистрибутивы программного обеспечения.

ВОЗМОЖНОСТИ
-----------

    - Синхронизация каталогов и файлов (репликация)
    - Простой механизм добавления файлов на ресурс - обычное копирование
    - Отсутствие необходимости конфигурирования, работа программы настраивается
      редактированием дескрипторных файлов
    - Возможность динамического добавления новых ресурсов (зеркал)
    - Установка проекта средствами CPAN или в ручном режиме через make install

ЗАВИСИМОСТИ
-----------

Перед началом установки, Вам необходимо проверить наличие следующих пакетов, установленных в Вашей
системе где будет "работать" App::DistSync:

    - gcc последней версии
    - perl v5.10 или выше (рекомендуется не ниже v5.12)
    - libwww (p5-libwww / perl-libwww)
    - libnet
    - httpd (apache) или nginx

УСТАНОВКА
---------

Установка выполняется двумя путями. Первый - автоматизированный; второй - ручной.

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

    # cpan install App::DistSync

или (для ActivePerl):

    # ppm install App-DistSync

В ручном режиме Вам потребуется выполнить следующий набор операций:

    - Скачать дистрибутив с CPAN или официальный релиз с сайта SourceForge:

      https://metacpan.org/pod/App::DistSync
      http://search.cpan.org/~abalama/
      https://sourceforge.net/projects/app-distsync/

    - Разархивировать полученный архив, и перейти в извлеченную папку с помощью
      командной строки консоли

    - Находясь в извлеченной папке выполнить последовательно следующие команды:

      perl Makefile.PL
      make
      make test
      make install

В процессе установки система предложит установить необходимые модули (пакеты),
их не так много и большая часть уже установлена на Вашей системе.

ИНИЦИАЛИЗАЦИЯ
-------------

Процесс инициализации создает структуру каталога ресурса. О файлах входящих в эту
структуру см. в следующем разделе.

Для инициализации следует выполнить следующую команду:

    # distsync -D /var/www/dist.mysite.com/path init

Опция -D указывает на ресурс, который будет объявлен зеркалом и там развернется
структура системных файлов, необходимых для работы

СТРУКТУРА КАТАЛОГА РЕСУРСОВ
---------------------------

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

META            НЕ РЕДАКТИРУЕМЫЙ YAML файл содержащий информацию о текущем
                ресурсе (каталоге на WEB сервере) и дате последней синхронизации

MANIFEST        НЕ РЕДАКТИРУЕМЫЙ файл, создаваемый автоматически при каждом запуске
                программы и отражающий текущую структуру каталога. По окончании
                синхронизации этот файл создается а в файле META модифицируется
                значение поля mtime. Структура файла:

                  DIRNAME/FILENAME   MTIME   SIZE MTIME_AS_STRING

                Следует заметить, что имена каталогов и файлов отделяются друг
                от друга с помощью слеша (/). Все пути относительны каталога
                самомго ресурса. Данное правило распространяется на все файлы
                MANIFEST.* и MIRRORS.

MANIFEST.SKIP   Редактируемый файл, соедержит по умолчанию список текущих системных
                файлов, а также тех, которые не следует учитывать при создании
                файла MANIFEST. Все файлы перечисленные в этом списке НЕ БУДУТ
                синхронизироваться с зеркалами. Список файлов игнорируемых совместно
                со списком данного файла:

                  META
                  MANIFEST
                  MANIFEST.DEL
                  MANIFEST.SKIP
                  MANIFEST.LOCK
                  README

                Структура файла:

                  DIRNAME/FILENAME   COMMENT

MANIFEST.DEL    Редактируемый файл, содержит в себе имена файлов, которые следует
                удалить с ресурса в указанное dtime время. В процессах синхронизации
                список обрабатывается также как в случае с файлом MANIFEST.SKIP.
                DTIME - это смещение относительно времени модификации самого файла
                MANIFEST.DEL. По умолчанию, значение равное "+3d". Файл MANIFEST.DEL
                не синхронизируется, но удаленные ресурсы его скачивают, и мгновенно
                удаляют файлы объявленного списка у себя. По окончании процесса удаления
                старых файлов данный фал MANIFEST.DEL удаляется. Структура файла:

                  DIRNAME/FILENAME   DTIME

MIRRORS         Список URI ресурсов (зеркал). Адрес текущего ресурса должен быть также в
                данном файле. Файл MIRRORS должен скачиваться ресурсом аналогично всем
                остальным файлам. Файл является редактируемым. Есть хитрость - при
                начале процесса синхронизации происходит создание контрольного файла
                MANIFEST.LOCK. Данный файл содержит в себе "секретный ключ".
                Первым делом скачивается он, если он есть. И если скачавши его получено
                содержимое в виде нашего собственного ключа, то синхронизация данного
                каталога прекращается, т.к. удалось распознать самого себя. Далее, данный
                распознанный URI вносится в META файл. Таким образом ресурс распознает сам
                себя. Структура файла:

                  URI   COMMENT

MANIFEST.LOCK   НЕ РЕДАКТИРУЕМЫЙ системный файл. Создается в процессе начала работы
                программы. Если ДРУГАЯ программа на ДРУГОМ ресурсе встречает данный
                файл, то она перестает выполнять синхронизацию с данным хостом.
                Помимо этого файл содержит в себе токен-ключ, который укажет программе
                создавшей этот файл что происходит обращение к текущему ресурсу,
                и обработку следует прекратить а текущий адрес нужно внести в META.
                Использование данного файла предотвращает одновременный запуск копии
                синхронайзера на одном и том же ресурсе.

MANIFEST.TEMP   НЕ РЕДАКТИРУЕМЫЙ системный файл. Данный файл содержит в себе временные
                данные, скаченные с удаленных ресурсов.

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

НАЧАЛО РАБОТЫ
-------------

После успешной инициализации - переходим к редактированию системных файлов.

Если Вы уже создали ранее зеркало, то Вам достаточно будет отредактировать
список зеркал, который следует модифицировать, добавив в него адрес нового
ресурса. Файл списка зеркал - MIRRORS. Помимио этого, вновь созданный файл
MIRRORS следует передать на сервер любого из зеркал, объявленных в исходном
файле MIRRORS. Это необходио для того, чтобы другие зеркала смогли
пользоваться новым, Вами созданным зерклом.

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

    # distsync -D /var/www/dist.mysite.com/path sync -d

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

Существует ряд ключевых опций команды:

    -D DATADIR

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

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

    # distsync -h

ПРОМЫШЛЕННОЕ ИСПОЛЬЗОВАНИЕ
--------------------------

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

Вот таким образом может выглядеть задача по выполнению автоматической синхронизации:

    37 * * * * /usr/bin/distsync -D /var/www/dist >/dev/null 2>>/var/log/distsync.log

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

Всю информацию об ошибках, можно смотреть в файле /var/log/distsync.log

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

Для удаления файлов следует редактировать файл MANIFEST.DEL, далее система сделает
все сама. По желанию после добавления строк в MANIFEST.DEL можно удалить файл с
диска физически.

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

Следует заметить, что НЕЛЬЗЯ переименовывать и перемещать файлы и папки, т.к.
при следуюшей синхронизации будет автоматически созданы отсутствующие файлы и на
других зерклах будут создны новые созданные файлы и папки.

__END__