Svacer Wiki - User contributions [en]

Svacer

2022-12-26T15:59:11Z

Vmonakhov:

MediaWiki has been installed.

Consult the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents User's Guide] for information on using the wiki software.

=== Руководство по использованию и администрированию сервера историй [[Help:Contents|'''Svacer''']] ===

== Getting started ==
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/postorius/lists/mediawiki-announce.lists.wikimedia.org/ MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Svacer

2022-12-26T15:42:55Z

Vmonakhov:

MediaWiki has been installed.

Consult the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents User's Guide] for information on using the wiki software.

=== Руководство по использованию сервера историй [[Help:Contents|'''Svacer''']] ===

== Getting started ==
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/postorius/lists/mediawiki-announce.lists.wikimedia.org/ MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Svacer

2022-12-26T15:42:07Z

Vmonakhov:

MediaWiki has been installed.

Consult the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents User's Guide] for information on using the wiki software.

== Руководство по использованию сервера историй [[Help:Contents|'''Svacer''']] ==

== Getting started ==
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/postorius/lists/mediawiki-announce.lists.wikimedia.org/ MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Svacer

2022-12-26T15:40:44Z

Vmonakhov:

== Руководство по использованию сервера историй [[Help:Contents|'''Svacer''']] ==

MediaWiki has been installed.

Consult the [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents User's Guide] for information on using the wiki software.

== Getting started ==
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/postorius/lists/mediawiki-announce.lists.wikimedia.org/ MediaWiki release mailing list]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Localisation#Translation_resources Localise MediaWiki for your language]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Combating_spam Learn how to combat spam on your wiki]

Help:Migration

2022-12-26T14:33:22Z

Vmonakhov:

[[Help:Contents|Все разделы]]
[[Category:Help]]
__TOC__

== Миграция ==
=== Миграция со старого сервера ===
В данном подразделе описана миграция со старого сервера, поставляющегося в комплекте со Svace. Это не относится к миграции между версиями Svacer. Миграция данных со старого сервера на Svacer состоит из двух этапов:
# Экспорт информации со старого сервера.
# Импорт данных в новый.

Для экспорта информации со старого Svace сервера используется утилита '''svace-migration.jar'''

java -jar svace-migration.jar <user> <password> <path to svace> <path to server dir> <path to output dir>

'''Параметры, используемые при экспорте данных'''
{| class="wikitable"
!Параметр!!Описание
|-
| <user>
| Имя пользователя на старом сервере
|-
| <password>
| Пароль пользователя на старом сервере
|-
| <path to svace>
| Путь к директории, где находится Svace
|-
| <path server dir>
| Директория, из которой запущен старый сервер
|-
| <path to output dir>
| Директория, в которую будут записаны экспортируемые данные
|}

Экспорт данных возможен при работающем старом сервере. Экспорт инкрементальный, поэтому ранее экспортированные результаты повторно не переносятся.
При экспорте утилита '''svace-migration.jar''' извлекает:

* все снимки в виде '''*.svres''';
* информацию о размещении исходного кода;
* сопутствующую информацию в директории старого сервера.

ВНИМАНИЕ: Для работы утилиты требуется Java 17+, при запуске возможно потребуется добавить опции JVM:
--add-opens java.base/java.lang.reflect=ALL-UNNAMED
--add-opens java.base/java.lang=ALL-UNNAMED
--add-opens java.base/java.io=ALL-UNNAMED
--add-opens java.base/java.util=ALL-UNNAMED
--add-opens java.base/java.util.concurrent=ALL-UNNAMED
--add-opens java.base/java.text=ALL-UNNAMED
--add-opens java.desktop/java.awt.font=ALL-UNNAMED

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

svacer migrate [--skip-dxr-errors] --distr <path to svace distr> --temp <path to temp folder> --store <intermediate store> <path to exported data>

'''Параметры, используемые при импорте данных'''
{| class="wikitable"
! Параметр !! Описание
|-
| --skip-dxr-errors
| Опциональный параметр для игнорирования ошибок в DXR-данных. Рекомендуется к использованию
|-
| --distr
| Путь к дистрибутиву Svace
|-
| --temp
| Директория для хранения временных файлов в ходе конверсии
|-
| --store
| Путь к промежуточному хранилищу
|-
| <path to exported data>
| Путь к директории, в которую были экспортированы результаты
|}

После конвертации данных в промежуточное хранилище результат можно загрузить на новый сервер с помощью команды upload:

svacer upload --user <user> --password <pwd> --host <host> --port <rest port> --grpc <grpc port> <path to store>

=== Миграция между версиями Svacer ===
Миграция БД PostgreSQL и object store между версиями Svacer происходит автоматически при обновлении на новую версию. Рекомендуется делать резервные копии перед обновлением (см. раздел [[#Создание и восстановление резервной копии|Создание и восстановление резервной копии]]).

Ниже описаны существенные изменения при переходе на определенную версию с более старой
* 4.0.1 и выше — миграция object store (badger) на новую версию. Может занимать существенное время при большом количестве проектов в Svacer. После перехода на версию 4.0.1 и выше object store становится несовместим с более ранними версиями
* 5.0.0 и выше — перенос DXR разметки из PostgreSQL в object store. Версии 5.0.0 и выше не совместимы с более ранними версиями.

=== Создание и восстановление резервной копии ===
==== Если PostgreSQL запущен в виде сервиса ====
Если PostgreSQL запущен в виде сервиса (т.е. не в докер-контейнере), то для создания резервной копии БД перейдите в пользователя postgres и запустите создание дампа:

sudo su -l postgres
pg_dump --clean -T tmp_diff* svacer_db > svacer.sql

где svacer_db — имя БД.

В результате дамп БД будет создан в файле svacer.sql

Для восстановления БД из дампа также перейдите в пользователя postgres и запустите восстановление
sudo su -l postgres
psql -f svacer.sql svacer_db

==== Если PostgreSQL запущен в docker-контейнере ====
Если PostgreSQL запущен в docker-контейнере, то для создания резервной копии БД выполните следующую команду

docker exec -t svacer_postgres pg_dump --clean -T tmp_diff* -U postgres svacer_db > svacer.sql

где:
* svacer_postgres — имя docker-контейнера
* postgres — имя пользователя, под учётной записью которого создана БД
* svacer_db — имя БД

Для восстановления БД используйте команду

cat svacer.sql | docker exec -i svacer_postgres psql -U postgres svacer_db

==== Создание резервной копии svacer object store через command line API ====
Резервную копию object store можно создать, использовав следующую команду (доступна только пользователю с ролью admin)

svacer server backup --user admin --password <password> --file <filename>.kvbak

В результате object store будет сохранен в файл '''<filename>.kvbak'''

Для восстановления из резервной копии требуется при запуске сервера указать этот файл в опции '''--load-from-backup'''.

svacer server --pg <postgres_url> —store /home/svacer/new-store --load-from-backup <filename>.kvbak

Восстановление возможно только в пустой object store. То есть в данном примере директория '''/home/svacer/new-store''' должна быть пустой.

==== Создание резервной копии svacer object store в сервере PostgreSQL ====
Резервную копию object store можно сохранить в сервере PostgreSQL, который используется сервером Svacer. Данный механизм использует функциональность large object store из PostgreSQL. Функциональность по бэкапу object store в PostgreSQL является '''рекомендуемой стратегией''' по бэкапу object store.

Следующие команды подразумевают, что сервер развернут с портами по умолчанию на localhost. При необходимости, порты и адрес сервера могут быть указаны как дополнительные опции.

Создание бэкапа:

svacer server backup --user admin --password <password> --pg

Бэкап создается в фоновом процессе, пользователь может продолжать работать с сервером. Результат работы команды состоит из ID бэкапа и времени создания. Эти данные печатаются в stdout

ID = 23 CREATE_TS = 2022-10-06T06:04:33Z

Для печати списка существующих бэкапов используется команда:

svacer server backup --user admin --password <password> --list-pg

Результат печатается в stdout и включает ID и время создания бэкапа

2022-10-06T09:04:36.929+0300 info Quering server configuration from http://localhost:8080/api/public/server/info
2022-10-06T09:04:36.930+0300 info Server configuration grpc = 3002, rest = 8080
2022-10-06T09:04:36.939+0300 info Logged by user admin
2022-10-06T09:04:36.941+0300 info Backups:
ID = 23 CREATE_TS = 2022-10-06T06:04:33Z

Восстановление object store из бэкапа допустимо только при старте сервера. Для этого следует очистить текущий object store (или указать путь на новую директорию) и использовать следующий флаг при старте:

svacer server --load-from-pg-backup=<id>

где <id> — ID бэкапа или 0, для использования последнего доступного бэкапа.

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

svacer server backup --user admin --password <password> --drop-pg=<lower>:<upper>

где <lower> и <upper> нижняя и верхняя граница ID бэкапов.

Настоятельно рекомендуется настроить задачу на хосте, где работает Svacer на периодический запуск бэкапа object store в PostgreSQL.

==== Создание резервной копии svacer object store вручную ====
Создать резервную копию object store также возможно вручную. Для этого достаточно скопировать директорию, в которой object store находится. Перед тем как это делать желательно остановить сервер Svacer в целях обеспечения целостности данных.

Если директория, где хранить '''object store''' не была явно указана при запуске сервера, по умолчанию он будет создан в следующей директории:

* ~/.cache/svacer — в OC Linux
* %LocalAppData%\svacer — в ОС Windows

(например, С:\Users\myusername\AppData\Local\svacer)

При восстановлении из резервной копии следуют поместить файлы object store в директорию по умолчанию (см. выше), либо же в другую директорию и при запуске Svacer указать путь к ней одним из способов:

# Перед запуском Svacer установить переменную окружения SVACER_OBJECT_STORE, например:
#: export SVACER_OBJECT_STORE=/home/user/data/object_store
# При запуске Svacer передать путь к object store в параметре --store, например:
#: svacer --store /home/user/data/object_store

При запуске Svacer в docker-контейнере требуется смонтировать директорию с object store в контейнер как volume и указать путь к ней в переменной '''STORE''' в файле '''docker-compose.yml'''. Допустим, директория с object store была скопирована в '''/home/user/data/object_store'''. В таком случае параметры нужно указать следующим образом

volumes:
- /home/user/data:/data
environment:
- STORE=/data/object_store

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

'''Внимание''': в текущей версии экспорт снимка из веб-интерфейса доступен всем пользователям с ролью READ для выбранного проекта/ветки. Импорт снимка из веб-интерфейса доступен только пользователям с ролью admin (обычный пользователь не видит секцию с проектами). Экспорт и импорт снимков из интерфейса командной строки доступен пользователям с ролями READ и WRITE для выбранной ветки.

==== Перенос из веб интерфейса ====
Для экспортирования снимка из пользовательского интерфейса пользователь может использовать кнопку экспорта на панели информации о снимке:

[[File:SnapshotInfo2.png|none|left|alt=SnapshotInfo window]]

либо использовать соответствующую функциональность из панели настроек проектов (требует роль admin):

[[File:CreateNewProject.png|none|left|alt=CreateNewProject window]]

Импортирование снимка через пользовательский интерфейс допустимо только для пользователя с ролью «admin». Команда доступна в меню ветки

[[File:BranchMenu.png|none|left|alt=BranchMenu windows]]

Задача по экспорту снимка может занимать значительное время (зависит от размера снимка) и выполняется асинхронным образом. Извещение о завершении задачи по экспорту появится в виде всплывающей зеленой панели а так же будет доступно в панели нотификаций:

[[File:Notifications.png|none|left|alt=Notifications window]]

[[File:NotificationsClearAll.png|none|left|alt=NotificationsClearAll window]]

==== Перенос из командной строки ====
Экспорт и импорт снимков из командной строки доступен пользователям с ролями READ и WRITE на проекте или ветке.

Экспорт снимков:
svacer server export
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--snapshot <snapshot name or id>
<output file name>

Импорт снимков:
svacer server import
--user <user>
--password <pwd>
--host <host>
--port <port>
--grpc <grpc port>
--project <project name or id>
--branch <branch name or id>
--name <new name for snapshot>
[--force]
<input file name>

Опция '''--force''' создаст проект и ветку, если их не было на сервере.

=== Перенос Svacer с одного сервера на другой ===

# Создайте резервную копию БД и object store в соответствии с тем, как описано в разделе [[#Создание и восстановление резервной копии|Создание и восстановление резервной копии]].
# Перенесите созданные файлы резервных копий на нужный сервер
# Восстановите данные из резервной копии на новом сервере

[[#Top|Вверх]]

Help:Installation

2022-12-26T14:31:38Z

Vmonakhov:

[[Help:Contents|Все разделы]]
[[Category:Help]]
__TOC__

== Установка ==
Для работы сервера необходим PostgreSQL. Его можно установить как пакет, либо запустить в докере — docker-compose файл для этого находится в '''./extra/docker-compose-postgres.yml'''.
Svacer сервер состоит из единственного бинарного файла — '''svacer'''. Он предоставляет как backend-часть, так и веб-сервер, который передаёт статику. По умолчанию запускается на порту 8080.
После запуска по умолчанию создается учётная запись пользователя '''admin''' c паролем '''admin'''. Изменить пароль можно в веб-интерфейсе.
Сервер имеет широкие возможности настройки параметров запуска. Узнать о них подробнее можно, прочитав '''svacer --help'''.

=== Установка и запуск из deb/rpm пакета ===
Процесс установки из .deb и .rpm пакетов несколько различается и будет описан ниже в отдельных главах. Процесс настройки и запуска не различается и будет описан в одной общей главе.

==== .deb ====
Скачайте .deb пакет релиза и выполните следующую команду

sudo apt install ./svacer_<version>_amd64.deb

При этом, если в репозиториях есть PostgreSQL нужной версии, он будет установлен автоматически. Если нет, то установка завершится с ошибкой о зависимости от PostgreSQL. В этом случае вам надо будет установить PostgreSQL версии не ниже 10-й (см. [https://www.postgresql.org/download/linux/ документацию]), после чего повторить установку Svacer.

==== .rpm ====
Установите PostgeSQL версии не ниже 10-й для вашей ОС следуя [https://www.postgresql.org/download/linux/redhat/ документации]. Дополнительно установите пакет postgresql-contrib из тех же репозиториев.

Пример для Centos 7 

sudo yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo yum install -y postgresql14-server postgresql14-contrib
sudo /usr/pgsql-14/bin/postgresql-14-setup initdb
sudo systemctl enable postgresql-14
sudo systemctl start postgresql-14

Для версий PostgreSQL ниже 13-й требуется явно разрешить подключение к локальному хосту базы с логином/паролем. Для этого проверьте следующие строчки в конце файла '''/var/lib/pgsql/<version>/data/pg_hba.conf'''

# IPv4 local connections:
host all all 127.0.0.1/32 ident 
# IPv6 local connections:
host all all ::1/128 ident

В случае если в последнем столбце указано значение '''ident''', поменяйте его на '''md5''' и перезапустите PostgreSQL.

sudo systemctl restart postgresql-12

Скачайте .rpm пакет релиза Svacer и выполните следующую команду

sudo yum install ./svacer-<version>.x86_64.rpm

==== Настройка и запуск ====
Процесс настройки и запуска одинаковый для Svacer установленного из .deb и .rpm пакетов.

В процессе установки создаются следующие файлы и директории
* /etc/default/svacer — конфигурационный файл
* /var/log/svacer — директория для логов
* /var/lib/svacer — директория для object store

После установки Svacer требуется создать пользователя и БД PostgreSQL. Для этого перейдите в пользователя postgres, запустите psql и выполните соответствующие запросы, после чего выйдите из консоли PostgreSQL и из пользователя postgres.

sudo su -l postgres
psql
postgres=# create database svace;
postgres=# create user svace with encrypted password 'svace';
postgres=# grant all privileges on database svace to svace;
postgres=# alter user svace superuser;

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

При использовании других имен пользователя, БД или пароля потребуется дополнительная конфигурация перед запуском Svacer: в файле '''/etc/default/svacer''' нужно поменять параметры подключения к БД в строке

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

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

После создания БД и настройки конфигурации Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

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

systemctl status svacer

В случае успешного запуска сервер будет доступен по адресу http://localhost:8080

При установке из .deb или .rpm пакета Svacer ставится в директорию, прописанную в $PATH, поэтому при запуске Svacer для импорта и загрузки результатов полный путь к исполняемому файлу '''svacer''' указывать не требуется, он будет доступен просто по имени.

=== Запуск в docker ===
Установите docker и docker-compose. Поскольку образы PostgreSQL и Svacer размещены на докер-хабе, для их скачивания при запуске необходимо наличие интернета.

Используйте для запуска docker-compose файл, находящийся в дистрибутиве Svacer: '''./extra/docker-compose.yml'''. Перейдите в директорию, где находится этот файл и выполните команду

docker-compose up -d

При этом будет запущено два контейнера: PostgreSQL и Svacer. После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080

В процессе запуска в текущей директории будут созданы две директории

* postgres_data — для хранения БД PostgreSQL
* svacer_data — для object store сервера Svacer

Эти директории будут примонтированы в соответствующие контейнеры как volumes, это необходимо для сохранения данных БД и сервера после остановки или перезапуска контейнеров.

Важное уточнение: в докере запускается только сервер Svacer. Для импорта и загрузки результатов на сервер будет нужен исполняемый файл svacer.

Остановить сервер Svacer можно, выполнив следующую команду

docker-compose down

Также можно запустить в докер-контейнере только PostgreSQL для последующего запуска Svacer вручную. Используйте файл '''./extra/docker-compose-postgres.yml'''

docker-compose -f docker-compose-postgres.yml up -d

Чтобы остановить, соответственно

docker-compose -f docker-compose-postgres.yml down

=== Установка и запуск вручную ===
Для установки Svacer скачайте и распакуйте архив дистрибутива (файл с названием вида '''svacer_release-<version>.zip''').

При использовании PostgreSQL, предварительно настроенного на каком-либо хосте, необходимо использовать соответствующие параметры запуска. Допустим, PostgreSQL работает на локальном хосте, в нем создана БД '''svacer_db''', доступная от пользователя '''svacer_user''' с паролем '''svacer123'''. В этом случае запустите Svacer со следующими параметрами

./bin/svacer server --pg postgres://svacer_user:svacer123@127.0.0.1:5432/svacer_db

Если вы запустили PostgreSQL в докер-контейнере, используя файл '''./extra/docker-compose-postgres.yml''', то при запуске Svacer параметр '''--pg''' для подключения к БД можно не указывать, поскольку был создан пользователь и база, прописанные в Svacer как параметры по умолчанию.

После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080
По умолчанию web сервер запускается на интерфейсе '''0.0.0.0:<port>'''. Для указания отличного сетевого интерфейса пользователь может использовать опцию '''--listen <network interface>'''.
По умолчанию grpc сервер запускается на интерфейсе '''0.0.0.0:<port>'''. Для указания отличного сетевого интерфейса пользователь может использовать опцию '''--listen-grpc <network interface>'''.

=== Hooks ===
Для получения данных Hooks при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий информацию о расширении сервера посредством хуков, которые пользователь может вызывать из web-интерфейса.
Каждый хук соответствует некоторому процессу или скрипту, который сервер запускает в ответ на вызов соответствующей команды из web-интерфейса.
Формат файла Hooks следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>",…],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, …]
},
...
]
}

'''Параметры Hooks'''
{| class="wikitable"
! style="width:100px;" | Параметр || Описание
|-
| ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. 
Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. 
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

[[#Top|Вверх]]

Help:Introduction

2022-12-26T14:30:16Z

Vmonakhov:

[[Help:Contents|Все разделы]]
[[Category:Help]]

__TOC__

== Введение ==
Сервер историй '''Svacer''' ('''''Svace Server''''') предназначен для хранения и обработки результатов работы статического анализатора Svace. Он разработан с целью заменить старый сервер историй, встроенный в анализатор Svace.
Допускается одновременное использование старого и нового серверов.

=== Термины ===

{| class="wikitable"
|-
| ''Project''
| Проект, подлежащий анализу. По умолчанию именем проекта считается имя директории, в которой был запущен ''svace build'' и ''svace analyze''.
На сервере проект содержит в себе несколько '''branch''' с результатами работы анализатора
|-
| ''Branch (ветка)''
| Ветка в проекте с результатами работы анализатора. По умолчанию проект имеет одну ветку — master
|-
| ''Snapshot (снимок)''
| Результат работы ''svace analyze'', импортированный в промежуточное хранилище или на сервер. Содержит:
* имя проекта;
* имя ветки;
* результаты анализа (предупреждения);
* исходники, которые были включены в build, на котором производился анализ;
* вспомогательная информация для навигации по исходникам;
* дополнительные данные;
Допускается импортирование снимков без исходного кода и дополнительной информации
|-
| ''Marker (маркер, предупреждение)''
| Предупреждение от Svace с информацией о позиции в исходном файле
|-
| ''Svacer''
| Svace History Server, а также исполняемый файл, содержащий код сервера
|-
| ''Разметка''
| Проставление статуса маркера с опциональным добавлением комментария
|}

=== Состав дистрибутива ===

{| class="wikitable"
|-
| '''bin/svacer bin/svacer.exe'''
| Бинарный файл сервера и утилита для импортирования результатов. Режим работы зависит от аргументов
|-
| '''support/svace-migration/svace-migration.jar'''
| Утилита подготовки данных для импорта из старого сервера историй.
Требует JDK для запуска. Может использоваться JDK из состава дистрибутива Svace
|-
| '''extra/docker-compose*.yml''' || Docker-compose файлы для запуска БД PostgreSQL и Svacer в docker-контейнерах
|-
| '''integrations/vscode''' || Расширение для Visual Studio Code и документация на него
|}

=== Зависимости ===

{| class="wikitable"
|-
| PostgreSQL
версии не ниже 10-й
| Параметры подключения определяются аргументом при запуске сервера или переменной окружения SVACER_PG_URL. По умолчанию, используется следующий connect URL:
'''postgres://svace:svace@0.0.0.0:5432/svace''' 
Можно использовать PostgreSQL в docker-контейнере. 
'''Настоятельно рекомендуем''' использовать выделенный сервер для хранения БД, особенно в production
|-
| libc.so libpthread.so libdl.so linux-vdso.so
| Серверная часть написана на Go с CGO_ENABLED=1 ввиду необходимости читать sqlite-файлы из результатов работы анализатора Svace
|-
| Выделенная директория для хранения object storage
| Сервер использует встроенную key-value database для хранения информации об исходном коде: контент-файлов и вспомогательной информации для навигации
|-
| svace
| Для импорта данных на сервер историй требуется наличие Svace на хосте, откуда происходит импорт. Svace используется для получения информации из .svace-dir
|}

=== Используемые порты ===

Приведены значения по умолчанию. Все значения могут быть переопределены.
{| class="wikitable"
|-
| 3002
| Используется для предоставления gRPC API.
gRPC API является внутренним и предназначен для загрузки данных на сервер
|-
| 8080
| Используется для предоставления REST API и web-сервера для предоставления web-UI
|}

[[#Top|Вверх]]

Help:Introduction

2022-12-26T14:29:58Z

Vmonakhov:

[[Category:Contents|Все разделы]]
[[Category:Help]]

__TOC__

== Введение ==
Сервер историй '''Svacer''' ('''''Svace Server''''') предназначен для хранения и обработки результатов работы статического анализатора Svace. Он разработан с целью заменить старый сервер историй, встроенный в анализатор Svace.
Допускается одновременное использование старого и нового серверов.

=== Термины ===

{| class="wikitable"
|-
| ''Project''
| Проект, подлежащий анализу. По умолчанию именем проекта считается имя директории, в которой был запущен ''svace build'' и ''svace analyze''.
На сервере проект содержит в себе несколько '''branch''' с результатами работы анализатора
|-
| ''Branch (ветка)''
| Ветка в проекте с результатами работы анализатора. По умолчанию проект имеет одну ветку — master
|-
| ''Snapshot (снимок)''
| Результат работы ''svace analyze'', импортированный в промежуточное хранилище или на сервер. Содержит:
* имя проекта;
* имя ветки;
* результаты анализа (предупреждения);
* исходники, которые были включены в build, на котором производился анализ;
* вспомогательная информация для навигации по исходникам;
* дополнительные данные;
Допускается импортирование снимков без исходного кода и дополнительной информации
|-
| ''Marker (маркер, предупреждение)''
| Предупреждение от Svace с информацией о позиции в исходном файле
|-
| ''Svacer''
| Svace History Server, а также исполняемый файл, содержащий код сервера
|-
| ''Разметка''
| Проставление статуса маркера с опциональным добавлением комментария
|}

=== Состав дистрибутива ===

{| class="wikitable"
|-
| '''bin/svacer bin/svacer.exe'''
| Бинарный файл сервера и утилита для импортирования результатов. Режим работы зависит от аргументов
|-
| '''support/svace-migration/svace-migration.jar'''
| Утилита подготовки данных для импорта из старого сервера историй.
Требует JDK для запуска. Может использоваться JDK из состава дистрибутива Svace
|-
| '''extra/docker-compose*.yml''' || Docker-compose файлы для запуска БД PostgreSQL и Svacer в docker-контейнерах
|-
| '''integrations/vscode''' || Расширение для Visual Studio Code и документация на него
|}

=== Зависимости ===

{| class="wikitable"
|-
| PostgreSQL
версии не ниже 10-й
| Параметры подключения определяются аргументом при запуске сервера или переменной окружения SVACER_PG_URL. По умолчанию, используется следующий connect URL:
'''postgres://svace:svace@0.0.0.0:5432/svace''' 
Можно использовать PostgreSQL в docker-контейнере. 
'''Настоятельно рекомендуем''' использовать выделенный сервер для хранения БД, особенно в production
|-
| libc.so libpthread.so libdl.so linux-vdso.so
| Серверная часть написана на Go с CGO_ENABLED=1 ввиду необходимости читать sqlite-файлы из результатов работы анализатора Svace
|-
| Выделенная директория для хранения object storage
| Сервер использует встроенную key-value database для хранения информации об исходном коде: контент-файлов и вспомогательной информации для навигации
|-
| svace
| Для импорта данных на сервер историй требуется наличие Svace на хосте, откуда происходит импорт. Svace используется для получения информации из .svace-dir
|}

=== Используемые порты ===

Приведены значения по умолчанию. Все значения могут быть переопределены.
{| class="wikitable"
|-
| 3002
| Используется для предоставления gRPC API.
gRPC API является внутренним и предназначен для загрузки данных на сервер
|-
| 8080
| Используется для предоставления REST API и web-сервера для предоставления web-UI
|}

[[#Top|Вверх]]

Help:Installation

2022-12-19T15:46:24Z

Vmonakhov:

[[Category:Help]]
[[:Category:Help]]
__TOC__

== Введение ==
[[Help:Introduction#Введение|[ Перейти ]]]

== Установка ==
Для работы сервера необходим PostgreSQL. Его можно установить как пакет, либо запустить в докере — docker-compose файл для этого находится в '''./extra/docker-compose-postgres.yml'''.
Svacer сервер состоит из единственного бинарного файла — '''svacer'''. Он предоставляет как backend-часть, так и веб-сервер, который передаёт статику. По умолчанию запускается на порту 8080.
После запуска по умолчанию создается учётная запись пользователя '''admin''' c паролем '''admin'''. Изменить пароль можно в веб-интерфейсе.
Сервер имеет широкие возможности настройки параметров запуска. Узнать о них подробнее можно, прочитав '''svacer --help'''.

=== Установка и запуск из deb/rpm пакета ===
Процесс установки из .deb и .rpm пакетов несколько различается и будет описан ниже в отдельных главах. Процесс настройки и запуска не различается и будет описан в одной общей главе.

==== .deb ====
Скачайте .deb пакет релиза и выполните следующую команду

sudo apt install ./svacer_<version>_amd64.deb

При этом, если в репозиториях есть PostgreSQL нужной версии, он будет установлен автоматически. Если нет, то установка завершится с ошибкой о зависимости от PostgreSQL. В этом случае вам надо будет установить PostgreSQL версии не ниже 10-й (см. [https://www.postgresql.org/download/linux/ документацию]), после чего повторить установку Svacer.

==== .rpm ====
Установите PostgeSQL версии не ниже 10-й для вашей ОС следуя [https://www.postgresql.org/download/linux/redhat/ документации]. Дополнительно установите пакет postgresql-contrib из тех же репозиториев.

Пример для Centos 7 

sudo yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo yum install -y postgresql14-server postgresql14-contrib
sudo /usr/pgsql-14/bin/postgresql-14-setup initdb
sudo systemctl enable postgresql-14
sudo systemctl start postgresql-14

Для версий PostgreSQL ниже 13-й требуется явно разрешить подключение к локальному хосту базы с логином/паролем. Для этого проверьте следующие строчки в конце файла '''/var/lib/pgsql/<version>/data/pg_hba.conf'''

# IPv4 local connections:
host all all 127.0.0.1/32 ident 
# IPv6 local connections:
host all all ::1/128 ident

В случае если в последнем столбце указано значение '''ident''', поменяйте его на '''md5''' и перезапустите PostgreSQL.

sudo systemctl restart postgresql-12

Скачайте .rpm пакет релиза Svacer и выполните следующую команду

sudo yum install ./svacer-<version>.x86_64.rpm

==== Настройка и запуск ====
Процесс настройки и запуска одинаковый для Svacer установленного из .deb и .rpm пакетов.

В процессе установки создаются следующие файлы и директории
* /etc/default/svacer — конфигурационный файл
* /var/log/svacer — директория для логов
* /var/lib/svacer — директория для object store

После установки Svacer требуется создать пользователя и БД PostgreSQL. Для этого перейдите в пользователя postgres, запустите psql и выполните соответствующие запросы, после чего выйдите из консоли PostgreSQL и из пользователя postgres.

sudo su -l postgres
psql
postgres=# create database svace;
postgres=# create user svace with encrypted password 'svace';
postgres=# grant all privileges on database svace to svace;
postgres=# alter user svace superuser;

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

При использовании других имен пользователя, БД или пароля потребуется дополнительная конфигурация перед запуском Svacer: в файле '''/etc/default/svacer''' нужно поменять параметры подключения к БД в строке

SVACER_ARGS="--pg postgres://<user>:<password>@127.0.0.1:5432/<database>"

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

После создания БД и настройки конфигурации Svacer запустить его можно следующими командами

sudo systemctl enable svacer
sudo systemctl start svacer

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

systemctl status svacer

В случае успешного запуска сервер будет доступен по адресу http://localhost:8080

При установке из .deb или .rpm пакета Svacer ставится в директорию, прописанную в $PATH, поэтому при запуске Svacer для импорта и загрузки результатов полный путь к исполняемому файлу '''svacer''' указывать не требуется, он будет доступен просто по имени.

=== Запуск в docker ===
Установите docker и docker-compose. Поскольку образы PostgreSQL и Svacer размещены на докер-хабе, для их скачивания при запуске необходимо наличие интернета.

Используйте для запуска docker-compose файл, находящийся в дистрибутиве Svacer: '''./extra/docker-compose.yml'''. Перейдите в директорию, где находится этот файл и выполните команду

docker-compose up -d

При этом будет запущено два контейнера: PostgreSQL и Svacer. После запуска контейнеров веб-интерфейс Svacer будет доступен по адресу http://localhost:8080

В процессе запуска в текущей директории будут созданы две директории

* postgres_data — для хранения БД PostgreSQL
* svacer_data — для object store сервера Svacer

Эти директории будут примонтированы в соответствующие контейнеры как volumes, это необходимо для сохранения данных БД и сервера после остановки или перезапуска контейнеров.

Важное уточнение: в докере запускается только сервер Svacer. Для импорта и загрузки результатов на сервер будет нужен исполняемый файл svacer.

Остановить сервер Svacer можно, выполнив следующую команду

docker-compose down

Также можно запустить в докер-контейнере только PostgreSQL для последующего запуска Svacer вручную. Используйте файл '''./extra/docker-compose-postgres.yml'''

docker-compose -f docker-compose-postgres.yml up -d

Чтобы остановить, соответственно

docker-compose -f docker-compose-postgres.yml down

=== Установка и запуск вручную ===
Для установки Svacer скачайте и распакуйте архив дистрибутива (файл с названием вида '''svacer_release-<version>.zip''').

При использовании PostgreSQL, предварительно настроенного на каком-либо хосте, необходимо использовать соответствующие параметры запуска. Допустим, PostgreSQL работает на локальном хосте, в нем создана БД '''svacer_db''', доступная от пользователя '''svacer_user''' с паролем '''svacer123'''. В этом случае запустите Svacer со следующими параметрами

./bin/svacer server --pg postgres://svacer_user:svacer123@127.0.0.1:5432/svacer_db

Если вы запустили PostgreSQL в докер-контейнере, используя файл '''./extra/docker-compose-postgres.yml''', то при запуске Svacer параметр '''--pg''' для подключения к БД можно не указывать, поскольку был создан пользователь и база, прописанные в Svacer как параметры по умолчанию.

После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080
По умолчанию web сервер запускается на интерфейсе '''0.0.0.0:<port>'''. Для указания отличного сетевого интерфейса пользователь может использовать опцию '''--listen <network interface>'''.
По умолчанию grpc сервер запускается на интерфейсе '''0.0.0.0:<port>'''. Для указания отличного сетевого интерфейса пользователь может использовать опцию '''--listen-grpc <network interface>'''.

=== Hooks ===
Для получения данных Hooks при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий информацию о расширении сервера посредством хуков, которые пользователь может вызывать из web-интерфейса.
Каждый хук соответствует некоторому процессу или скрипту, который сервер запускает в ответ на вызов соответствующей команды из web-интерфейса.
Формат файла Hooks следующий:
{
"hooks": [
{
"id": "<id>",
"label": "<label >",
"target": "<target>",
"input": ["<param1>", "<param2>",…],
"cmd": "<path to executable>",
"args": ["<arg1>", “<arg2>”, …]
},
...
]
}

'''Параметры Hooks'''
{| class="wikitable"
! style="width:100px;" | Параметр || Описание
|-
| ''id''
| Идентификатор хука. Должен быть уникальным в файле
|-
| ''label''
| Имя команды, которую пользователь видит в web-интерфейсе
|-
| ''target''
| Место в UI, в которое будет добавлена команда. 
Сейчас поддерживается только одно значение — default. Оно соответствует вкладке Details на правой панели пользовательского интерфейса
|-
| ''input''
| Параметры, которые можно передать в запускаемый процесс, исходя из контекста вызова команды в web-интерфейсе. 
Поддерживаемые значения:
* markerID — UUID идентификатор маркера;
* branchID — UUID идентификатор ветки;
* snapshotID — UUID идентификатор снимка;
* projectID — UUID идентификатор проекта;
* url — URL маркера в web-интерфейсе, на котором была вызвана команда;
* marker — будет заменен на полное имя временного файла, содержащего сериализованное в JSON представление маркера, который включает в себя его трассу и информацию о разметке
|-
| ''cmd''
| Полный путь к процессу, который будет запущен. Не должен включать аргументы запуска
|-
| ''args''
| Аргументы, передаваемые в запускаемый процесс. Полный список аргументов запускаемого процесса состоит из списка <args> и списка значений, соответствующих полю <input>
|}

[[#Top|Вверх]]

Help:Introduction

2022-12-19T15:46:02Z

Vmonakhov:

[[Category:Help]]
[[:Category:Help]]

__TOC__

== Введение ==
Сервер историй '''Svacer''' ('''''Svace Server''''') предназначен для хранения и обработки результатов работы статического анализатора Svace. Он разработан с целью заменить старый сервер историй, встроенный в анализатор Svace.
Допускается одновременное использование старого и нового серверов.

=== Термины ===

{| class="wikitable"
|-
| ''Project''
| Проект, подлежащий анализу. По умолчанию именем проекта считается имя директории, в которой был запущен ''svace build'' и ''svace analyze''.
На сервере проект содержит в себе несколько '''branch''' с результатами работы анализатора
|-
| ''Branch (ветка)''
| Ветка в проекте с результатами работы анализатора. По умолчанию проект имеет одну ветку — master
|-
| ''Snapshot (снимок)''
| Результат работы ''svace analyze'', импортированный в промежуточное хранилище или на сервер. Содержит:
* имя проекта;
* имя ветки;
* результаты анализа (предупреждения);
* исходники, которые были включены в build, на котором производился анализ;
* вспомогательная информация для навигации по исходникам;
* дополнительные данные;
Допускается импортирование снимков без исходного кода и дополнительной информации
|-
| ''Marker (маркер, предупреждение)''
| Предупреждение от Svace с информацией о позиции в исходном файле
|-
| ''Svacer''
| Svace History Server, а также исполняемый файл, содержащий код сервера
|-
| ''Разметка''
| Проставление статуса маркера с опциональным добавлением комментария
|}

=== Состав дистрибутива ===

{| class="wikitable"
|-
| '''bin/svacer bin/svacer.exe'''
| Бинарный файл сервера и утилита для импортирования результатов. Режим работы зависит от аргументов
|-
| '''support/svace-migration/svace-migration.jar'''
| Утилита подготовки данных для импорта из старого сервера историй.
Требует JDK для запуска. Может использоваться JDK из состава дистрибутива Svace
|-
| '''extra/docker-compose*.yml''' || Docker-compose файлы для запуска БД PostgreSQL и Svacer в docker-контейнерах
|-
| '''integrations/vscode''' || Расширение для Visual Studio Code и документация на него
|}

=== Зависимости ===

{| class="wikitable"
|-
| PostgreSQL
версии не ниже 10-й
| Параметры подключения определяются аргументом при запуске сервера или переменной окружения SVACER_PG_URL. По умолчанию, используется следующий connect URL:
'''postgres://svace:svace@0.0.0.0:5432/svace''' 
Можно использовать PostgreSQL в docker-контейнере. 
'''Настоятельно рекомендуем''' использовать выделенный сервер для хранения БД, особенно в production
|-
| libc.so libpthread.so libdl.so linux-vdso.so
| Серверная часть написана на Go с CGO_ENABLED=1 ввиду необходимости читать sqlite-файлы из результатов работы анализатора Svace
|-
| Выделенная директория для хранения object storage
| Сервер использует встроенную key-value database для хранения информации об исходном коде: контент-файлов и вспомогательной информации для навигации
|-
| svace
| Для импорта данных на сервер историй требуется наличие Svace на хосте, откуда происходит импорт. Svace используется для получения информации из .svace-dir
|}

=== Используемые порты ===

Приведены значения по умолчанию. Все значения могут быть переопределены.
{| class="wikitable"
|-
| 3002
| Используется для предоставления gRPC API.
gRPC API является внутренним и предназначен для загрузки данных на сервер
|-
| 8080
| Используется для предоставления REST API и web-сервера для предоставления web-UI
|}

[[#Top|Вверх]]

File:MarkupCopingBranch.png

2022-12-19T14:50:25Z

Vmonakhov:

MarkupCopingBranch

File:ChangeUserProfile.png

2022-12-19T14:29:32Z

Vmonakhov:

ChangeUserProfile

File:LdapServerChoose.png

2022-12-19T14:25:26Z

Vmonakhov:

LdapServerChoose

File:LdapServerAdded.png

2022-12-19T14:24:52Z

Vmonakhov:

LdapServerAdded

File:MarkupTemplateEditing.png

2022-12-19T14:21:38Z

Vmonakhov:

MarkupTemplateEditing

File:MarkupTemplates.png

2022-12-19T14:20:12Z

Vmonakhov:

MarkupTemplates

File:MarkupCoping.png

2022-12-19T14:18:20Z

Vmonakhov:

MarkupCoping

File:ServerInfo.png

2022-12-19T14:13:44Z

Vmonakhov:

ServerInfo

File:ProjectBranchesFilters.png

2022-12-19T14:12:34Z

Vmonakhov:

ProjectBranchesFilters

File:SnapshotImport.png

2022-12-19T14:11:12Z

Vmonakhov:

SnapshotImport

File:ProjectsList.png

2022-12-19T11:47:43Z

Vmonakhov:

ProjectsList

File:UnzipButton.png

2022-12-19T11:21:57Z

Vmonakhov:

UnzipButton

File:ArchiveButton.png

2022-12-19T11:20:22Z

Vmonakhov:

ArchiveButton

File:CreateNewRole.png

2022-12-19T11:16:15Z

Vmonakhov:

CreateNewRole

File:ChangePassword.png

2022-12-19T11:13:56Z

Vmonakhov:

ChangePassword

File:AddUser.png

2022-12-19T11:13:07Z

Vmonakhov:

AddUser

File:KeyButton.png

2022-12-19T11:04:36Z

Vmonakhov:

KeyButton

File:PreviewButton.png

2022-12-14T08:54:25Z

Vmonakhov:

PreviewButton

File:BlockButton.png

2022-12-14T08:10:56Z

Vmonakhov:

BlockButton

File:CancelButton.png

2022-12-14T08:08:43Z

Vmonakhov:

CancelButton

File:HistoryButton.png

2022-12-14T08:06:01Z

Vmonakhov:

HistoryButton

File:MinusButton.png

2022-12-14T07:59:45Z

Vmonakhov:

MinusButton

File:PlusButton.png

2022-12-14T07:59:08Z

Vmonakhov:

PlusButton

File:GroupByButton.png

2022-12-14T07:57:53Z

Vmonakhov:

GroupByButton

File:UnsetButton.png

2022-12-14T07:57:05Z

Vmonakhov:

UnsetButton

File:DeleteOrganizationButton.png

2022-12-14T07:55:44Z

Vmonakhov:

DeleteOrganizationButton

File:ChangeOrganizationButton.png

2022-12-14T07:48:52Z

Vmonakhov:

ChangeOrganizationButton

File:DialogMakeupExport.png

2022-12-13T15:09:59Z

Vmonakhov:

DialogMakeupExport

File:LockOnChekersPanel.png

2022-12-13T14:47:18Z

Vmonakhov:

LockOnChekersPanel

File:LockOnFilesPanel.png

2022-12-13T14:46:40Z

Vmonakhov:

LockOnFilesPanel

File:LockOnMakeupPanel.png

2022-12-13T14:45:48Z

Vmonakhov:

LockOnMakeupPanel

File:ReviewLocksPanel.png

2022-12-13T14:44:31Z

Vmonakhov:

ReviewLocksPanel

File:ExportMakeupCode.png

2022-12-13T14:41:21Z

Vmonakhov:

ExportMakeupCode

File:NotificationsAfterGroupMakeup.png

2022-12-13T13:56:13Z

Vmonakhov:

NotificationsAfterGroupMakeup

File:GroupMakeupWindowWithButtons.png

2022-12-13T13:52:35Z

Vmonakhov:

GroupMakeupWindowWithButtons

File:MakeupNotifications.png

2022-12-13T13:49:26Z

Vmonakhov:

MakeupNotifications

File:GroupMakeupWindow.png

2022-12-13T12:18:31Z

Vmonakhov:

GroupMakeupWindow

File:ReviewMarkersButton.png

2022-12-13T12:17:17Z

Vmonakhov:

ReviewMarkersButton

File:MakeupHistory.png

2022-12-13T12:12:35Z

Vmonakhov:

MakeupHistory

File:MakeupButtons.png

2022-12-13T12:04:08Z

Vmonakhov:

MakeupButtons