Help:Installation: Difference between revisions

From Svacer Wiki
Jump to navigation Jump to search
No edit summary
(add dockerfile link)
(39 intermediate revisions by 3 users not shown)
Line 1: Line 1:
[[Category:Help]]
[[Category:Help]]
[[:Category:Help]]
== Установка и запуск ==
__TOC__
 
 
== Установка ==
Для работы сервера необходим PostgreSQL. Его можно установить как пакет, либо запустить в докере — docker-compose файл для этого находится в '''./extra/docker-compose-postgres.yml'''.
Для работы сервера необходим PostgreSQL. Его можно установить как пакет, либо запустить в докере — docker-compose файл для этого находится в '''./extra/docker-compose-postgres.yml'''.
Svacer сервер состоит из единственного бинарного файла — '''svacer'''. Он предоставляет как backend-часть, так и веб-сервер, который передаёт статику. По умолчанию запускается на порту 8080.
Svacer состоит из единственного бинарного файла. Он предоставляет как backend-часть, так и веб-сервер, который передаёт статику. По умолчанию запускается на порту 8080.
После запуска по умолчанию создается учётная запись пользователя '''admin''' c паролем '''admin'''. Изменить пароль можно в веб-интерфейсе.
После запуска по умолчанию создается учётная запись пользователя '''admin''' c паролем '''admin'''. Изменить пароль можно в веб-интерфейсе.
Сервер имеет широкие возможности настройки параметров запуска. Узнать о них подробнее можно, прочитав '''svacer --help'''.
Сервер имеет широкие возможности настройки параметров запуска. Узнать о них подробнее можно, прочитав '''svacer --help'''.


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


=== Установка и запуск из deb/rpm пакета ===
<pre>
Процесс установки из .deb и .rpm пакетов несколько различается и будет описан ниже в отдельных главах. Процесс настройки и запуска не различается и будет описан в одной общей главе.
  echo 'deb https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list
  wget -q -O - https://repo.ispras.ru/apt/key.asc | sudo apt-key add -
  sudo apt update
  sudo apt install -y svacer
</pre>
 
Если нет возможности установить из репозитория (допустим, на машине без доступа к интернету), скачайте .deb пакет релиза и выполните следующую команду
 
  sudo apt install ./svacer_<version>_amd64.deb
 
Если вы планируете использовать Svacer только как клиент для взаимодействия с сервером, то больше ничего устанавливать и конфигурировать не нужно.  


Если планируете использовать Svacer как сервер, установите (или [[Help:Installation#Запуск_в_docker_только_PostgreSQL|запустите в докере]]) PostgreSQL версии не ниже 10-й.


==== .deb ====
На debian-based системах, обычно, чтобы установить PostgreSQL достаточно выполнить команду
Скачайте .deb пакет релиза и выполните следующую команду


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


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


После установки [[Help:Installation#Настройка_и_запуск|создайте БД и запустите сервер Svacer]].


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


Пример для Centos 7<br>
  sudo yum install ./svacer-<version>.x86_64.rpm


    sudo yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
Если вы планируете использовать Svacer только как клиент для взаимодействия с сервером, то больше ничего устанавливать и конфигурировать не нужно.  
    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'''
Если планируете использовать Svacer как сервер, установите (или [[Help:Installation#Запуск_в_docker_только_PostgreSQL|запустите в докере]]) PostgreSQL версии не ниже 10, следуя [https://www.postgresql.org/download/linux/redhat/ документации], также установите пакет postgresql-contrib из тех же репозиториев.


    # IPv4 local connections:
Пример для Centos 7
    host    all    all    127.0.0.1/32    ident


    # IPv6 local connections:
<pre>
    host    all    all    ::1/128        ident
  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
</pre>


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


'''sudo systemctl restart postgresql-12'''
  # IPv4 local connections:
  host    all    all    127.0.0.1/32    ident<br>
  # IPv6 local connections:
  host    all    all    ::1/128        ident


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


'''sudo yum install ./svacer-<version>.x86_64.rpm'''
  sudo systemctl restart postgresql-12


После установки [[Help:Installation#Настройка_и_запуск|создайте БД и запустите сервер Svacer]].


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


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


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


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


В этой же строке можно указывать прочие аргументы для запуска сервера Svacer.
В этой же строке можно указывать прочие аргументы для запуска сервера Svacer.
Line 78: Line 94:
После создания БД и настройки конфигурации Svacer запустить его можно следующими командами
После создания БД и настройки конфигурации Svacer запустить его можно следующими командами


    sudo systemctl enable svacer
  sudo systemctl enable svacer
    sudo systemctl start svacer
  sudo systemctl start svacer


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


    systemctl status svacer
  systemctl status svacer


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


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


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


    docker-compose up -d
  docker-compose up -d


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


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


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


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


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


    docker-compose down
  docker-compose down


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


    docker-compose -f docker-compose-postgres.yml up -d
==== Запуск в docker только PostgreSQL ====
Также можно запустить в докер-контейнере только PostgreSQL. Используйте файл '''./extra/docker-compose-postgres.yml'''
 
  docker-compose -f docker-compose-postgres.yml up -d


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


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


При таком способе запуска создается пользователь и база, указанные в Svacer как параметры по умолчанию, поэтому при запуске сервера Svacer параметр '''--pg''' можно не указывать (и не менять в конфиг-файле '''/etc/default/svacer''' при установке Svacer из пакетов).


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


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


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


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


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


=== Установка и запуск на Windows ===
==== Установка вручную ====
Далее будут описаны шаги установки и запуска Svacer как сервера. Для использования Svacer только как клиента установка и настройка БД PostgreSQL не требуется, достаточно распаковать архив дистрибутива и использовать файл '''bin/svacer.exe'''.
* Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
* Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
* Задайте и запомните пароль на шаге выбора пароля для суперпользователя
* Остальные параметры при установке можно оставить по умолчанию
* После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
  cd c:\Program Files\PostgreSQL\15\bin
  psql -U postgres
* Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
  create database svace;
  create user svace with encrypted password 'svace';
  grant all privileges on database svace to svace;
  alter user svace superuser;
* Выйдите из консоли PostgreSQL
* Скачайте и распакуйте архив дистрибутива Svacer (файл с названием '''svacer_release-<version>.zip''')
* В консоли перейдите в директорию дистрибутива и запустите '''svacer.exe'''. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
  cd svacer-release-6-0-3
  bin\svacer.exe server
* Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
  bin\svacer.exe server --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
* После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080
==== Установка из .msi ====
* Запустите файл установщика '''svacer-<version>.msi'''. Если появляется окно с предупреждением и текстом "Windows protected your PC", нажмите в нем "More info", а после — кнопку "Run anyway". Cледуйте шагам для установки Svacer
* После завершения установки Svacer будет добавлен в PATH, поэтому можно будет запускать его просто по имени, без полного пути
* Если планируется использовать Svacer только как клиент, то больше никаких действий не требуется
* Если нужно запустить Svacer как сервер — установите и настройте БД PostgreSQL как описано в предыдущей главе
* После настройки PostgreSQL запустите '''svacer.exe''' с указанием параметров подключения к БД аналогично тому, как описано в предыдущей главе
* Также для запуска сервера можете использовать скрипт '''start_svacer_server.cmd''', он устанавливается туда же, куда и сам Svacer и тоже добавляется в PATH. Перед запуском в этом скрипте можете поменять параметры подключения к БД (или не менять, если при создании БД использовали имя по умолчанию 'svace')
== Расширенная конфигурация ==
=== Настройка HTTPS ===
Svacer пока не поддерживает HTTPS нативно, поэтому стандартный способ настроить взаимодействие с ним по этому протоколу — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP.
==== Nginx ====
Создайте конфигурационный файл с подобным содержанием в '''/etc/nginx/sites-enabled/'''
<pre>
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name svacer.ispras.ru;
    # for large data transfers and continuous connections
    client_max_body_size        0;
    proxy_connect_timeout      600;
    proxy_send_timeout          600;
    proxy_read_timeout          600;
    send_timeout                600;
    # path to ssl-certificate and key
    ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
    ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;
    location / {
        include proxy_params;
        # to make WebSockets work
        proxy_http_version  1.1;
        proxy_set_header    Upgrade $http_upgrade;
        proxy_set_header    Connection "upgrade";


=== Hooks ===
        # svacer HTTP URL
Для получения данных Hooks при запуске сервера нужно указать опцию '''--hooks <path to JSON file>'''. Эта опция задаёт файл, содержащий информацию о расширении сервера посредством хуков, которые пользователь может вызывать из web-интерфейса.
         proxy_pass http://127.0.0.1:8080;
Каждый хук соответствует некоторому процессу или скрипту, который сервер запускает в ответ на вызов соответствующей команды из web-интерфейса.
Формат файла Hooks следующий:
    {
      "hooks": [
         {
          "id": "<id>",
          "label": "<label >",
          "target": "<target>",
          "input": ["<param1>", "<param2>",…],
          "cmd": "<path to executable>",
          "args": ["<arg1>", “<arg2>”, …]
        },
        ...
      ]
     }
     }
}
</pre>
В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.
  systemctl restart nginx
Также, если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. [https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/ эту инструкцию].
==== Apache ====
Включите нужные модули в Apache
  sudo a2enmod ssl proxy proxy_http
Создайте конфигурационный файл с подобным содержанием в '''/etc/apache2/sites-enabled/'''
<pre>
<VirtualHost *:443>
    SSLEngine On
    ProxyPreserveHost On
    ProxyTimeout 600
   
    # path to ssl-certificate and key
    SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
    SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key
   
    # to make WebSockets work
    ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
    ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/
    # svacer HTTP URL
    ProxyPass / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/
    ServerName svacer.ispras.ru
    ServerAdmin svacer@ispras.ru
</VirtualHost>
</pre>
В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.
  systemctl restart apache2
==== Нативно ====
По умолчанию сервер запускается без поддержки SSL/TLS, при этом в логах отображается информация об этом.
TLS for REST and gRPC DISABLED
Для запуска сервера с поддержкой TLS необходимо указать сертификат сервера и соответствующий закрытый ключ.
svacer server --ssl-cert svacer.crt --ssl-key svacer.key
При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.
Работа сервера по проктолу TLS сопровождается следующей записью в логе:
Using TLS for REST and gRPC protocols
Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре '''--host''', либо добавить опцию '''--ssl'''.
<pre>
svacer upload --host https://example.com
svacer upload --ssl --host example.com
</pre>
Также в клиенте можно определить параметр '''--ssl-ca-certs'''. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:
Using weak TLS configuration, because no CA certificate found
Если сертификаты были загружены, в логе будет строчка:
added 1 ca certs from /home/user/svacer/svacer.crt
Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: '''server:config'''. В данной области есть 3 команды: '''show''', '''reload''', '''update'''. ID в этом случае нужно всегда указывать в значение '''ssl.cert'''.
* '''show''' — отображает текущий используемый сертификат
:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show</pre>
* '''reload''' — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом
:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload</pre>
* '''update''' — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете '''cat''' для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.


:<pre>svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem</pre>


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


=== Выбор сетевых интерфейсов и портов сервера ===


[[#Top|В начало]]
* По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 ('''0.0.0.0:8080'''). Для указания конкретного сетевого интерфейса можно использовать опцию '''--listen <network interface>''', для указания другого порта: '''--port <port_number>.
* Аналогично для grpc-сервера: по умолчанию — '''0.0.0.0:3002''', для выбора конкретного интерфейса: '''--listen-grpc <network_interface>''', для указания другого порта: '''--grpc <port_number>'''.
Пример:
  svacer server --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004

Revision as of 13:04, 14 March 2023

Установка и запуск

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

Установка и запуск из deb/rpm пакета

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

.deb

Добавьте наш apt-репозиторий и установите Svacer из него.

  echo 'deb https://repo.ispras.ru/apt /' | sudo tee /etc/apt/sources.list.d/ispras.list
  wget -q -O - https://repo.ispras.ru/apt/key.asc | sudo apt-key add -
  sudo apt update
  sudo apt install -y svacer

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

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

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

Если планируете использовать Svacer как сервер, установите (или запустите в докере) PostgreSQL версии не ниже 10-й.

На debian-based системах, обычно, чтобы установить PostgreSQL достаточно выполнить команду

 sudo apt install postgresql

Если такая команда не работает, возможно, в репозиториях вашей ОС нет PostgreSQL. В таком случае обратитесь к руководству по установке PostgreSQL.

После установки создайте БД и запустите сервер Svacer.

.rpm

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

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

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

Если планируете использовать Svacer как сервер, установите (или запустите в докере) PostgreSQL версии не ниже 10-й, следуя документации, также установите пакет 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

После установки создайте БД и запустите сервер Svacer.

Настройка и запуск

Процесс настройки и запуска одинаковый для 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

Запуск в 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

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

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

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

 docker-compose down

Для сборки своего докер-образа Svacer-а можете использовать наш Dockerfile в качестве референса.

Запуск в docker только PostgreSQL

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

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

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

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

При таком способе запуска создается пользователь и база, указанные в Svacer как параметры по умолчанию, поэтому при запуске сервера Svacer параметр --pg можно не указывать (и не менять в конфиг-файле /etc/default/svacer при установке Svacer из пакетов).

Установка и запуск вручную

Для установки 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

Установка и запуск на Windows

Установка вручную

Далее будут описаны шаги установки и запуска Svacer как сервера. Для использования Svacer только как клиента установка и настройка БД PostgreSQL не требуется, достаточно распаковать архив дистрибутива и использовать файл bin/svacer.exe.

  • Скачайте установщик PostgreSQL для Windows: https://www.postgresql.org/download/windows
  • Установите PostgreSQL, выбрав, как минимум, компоненты "PostgreSQL Server" и "Command Line Tools"
  • Задайте и запомните пароль на шаге выбора пароля для суперпользователя
  • Остальные параметры при установке можно оставить по умолчанию
  • После установки PostgreSQL откройте консоль, перейдите в директорию, куда установили PostgreSQL, запустите его клиент с указанием пользователя "postgres" и авторизуйтесь с паролем, заданным во время установки
 cd c:\Program Files\PostgreSQL\15\bin
 psql -U postgres
  • Запустится консоль управления PostgreSQL. Выполните в ней следующие команды, чтобы создать БД и пользователя для Svacer
 create database svace;
 create user svace with encrypted password 'svace';
 grant all privileges on database svace to svace;
 alter user svace superuser;
  • Выйдите из консоли PostgreSQL
  • Скачайте и распакуйте архив дистрибутива Svacer (файл с названием svacer_release-<version>.zip)
  • В консоли перейдите в директорию дистрибутива и запустите svacer.exe. Если при создании пользователя и БД PostgreSQL вы использовали для них имя по умолчанию 'svace', как в примере выше, то указывать данные для подключения к БД при запуске сервера не обязательно
 cd svacer-release-6-0-3
 bin\svacer.exe server
  • Если создавали пользователя или БД с другими именами, то при запуске сервера надо указать их явно
 bin\svacer.exe server --pg postgres://svacer_user:svacer_password@127.0.0.1:5432/svacer_database
  • После запуска сервера его веб-интерфейс будет доступен по адресу http://localhost:8080

Установка из .msi

  • Запустите файл установщика svacer-<version>.msi. Если появляется окно с предупреждением и текстом "Windows protected your PC", нажмите в нем "More info", а после — кнопку "Run anyway". Cледуйте шагам для установки Svacer
  • После завершения установки Svacer будет добавлен в PATH, поэтому можно будет запускать его просто по имени, без полного пути
  • Если планируется использовать Svacer только как клиент, то больше никаких действий не требуется
  • Если нужно запустить Svacer как сервер — установите и настройте БД PostgreSQL как описано в предыдущей главе
  • После настройки PostgreSQL запустите svacer.exe с указанием параметров подключения к БД аналогично тому, как описано в предыдущей главе
  • Также для запуска сервера можете использовать скрипт start_svacer_server.cmd, он устанавливается туда же, куда и сам Svacer и тоже добавляется в PATH. Перед запуском в этом скрипте можете поменять параметры подключения к БД (или не менять, если при создании БД использовали имя по умолчанию 'svace')

Расширенная конфигурация

Настройка HTTPS

Svacer пока не поддерживает HTTPS нативно, поэтому стандартный способ настроить взаимодействие с ним по этому протоколу — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP.

Nginx

Создайте конфигурационный файл с подобным содержанием в /etc/nginx/sites-enabled/

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name svacer.ispras.ru;

    # for large data transfers and continuous connections
    client_max_body_size        0;
    proxy_connect_timeout       600;
    proxy_send_timeout          600;
    proxy_read_timeout          600;
    send_timeout                600;

    # path to ssl-certificate and key
    ssl_certificate /etc/ssl/certs/svacer.ispras.ru.crt;
    ssl_certificate_key /etc/ssl/private/svacer.ispras.ru.key;

    location / {
        include proxy_params;

        # to make WebSockets work
        proxy_http_version  1.1;
        proxy_set_header    Upgrade $http_upgrade;
        proxy_set_header    Connection "upgrade";

        # svacer HTTP URL
        proxy_pass http://127.0.0.1:8080;
    }
}

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Nginx.

 systemctl restart nginx

Также, если ваш сервер виден из интернета и его внешний IP-адрес привязан к доменному имени, можете использовать Let's Encrypt и Certbot для получения валидного SSL-сертификата. См. эту инструкцию.

Apache

Включите нужные модули в Apache

 sudo a2enmod ssl proxy proxy_http

Создайте конфигурационный файл с подобным содержанием в /etc/apache2/sites-enabled/

<VirtualHost *:443>
    SSLEngine On
    ProxyPreserveHost On
    ProxyTimeout 600
    
    # path to ssl-certificate and key
    SSLCertificateFile /etc/ssl/certs/svacer.ispras.ru.crt
    SSLCertificateKeyFile /etc/ssl/private/svacer.ispras.ru.key
    
    # to make WebSockets work
    ProxyPass /api/ws/ ws://127.0.0.1:8080/api/ws/
    ProxyPassReverse /api/ws/ ws://127.0.0.1:8080/api/ws/

    # svacer HTTP URL
    ProxyPass / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/

    ServerName svacer.ispras.ru
    ServerAdmin svacer@ispras.ru
</VirtualHost>

В этом конфигурационном файле укажите нужное имя сервера, пути к сертификату (можно использовать fullchain-сертификат) и ключу, а также адрес сервера Svacer, куда проксировать. После этого перезапустите Apache.

 systemctl restart apache2

Нативно

По умолчанию сервер запускается без поддержки SSL/TLS, при этом в логах отображается информация об этом.

TLS for REST and gRPC DISABLED

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

svacer server --ssl-cert svacer.crt --ssl-key svacer.key

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Формат файла — PEM. TLS соединение активируется и для протокола REST и для протокола gRPC.

Работа сервера по проктолу TLS сопровождается следующей записью в логе:

Using TLS for REST and gRPC protocols

Работа с таким сервером через CLI происходит как обычно. Для указания необходимости подключаться по TLS можно явно указать протокол в параметре --host, либо добавить опцию --ssl.

 svacer upload --host https://example.com
 svacer upload --ssl --host example.com

Также в клиенте можно определить параметр --ssl-ca-certs. Он позволяет задать доверенные сертификаты корневых центров. Указывается шаблон файлов (с *) или конкретный файл. Путь к директории должен быть абсолютным. В случае отсутствия этого параметра используется TLS, но сертификат сервера не проверяется. Этому случаю соответствует запись в логе клиента:

Using weak TLS configuration, because no CA certificate found

Если сертификаты были загружены, в логе будет строчка:

added 1 ca certs from /home/user/svacer/svacer.crt

Для администрирования сервера в плане используемого сертификата (например, замена при истечении срока действия) добавлена область в CLI svacer admin: server:config. В данной области есть 3 команды: show, reload, update. ID в этом случае нужно всегда указывать в значение ssl.cert.

  • show — отображает текущий используемый сертификат
svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action show
  • reload — заставляет сервер перечитать использованные при старте сервера файлы с сертификатом и ключом
svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action reload
  • update — позволяет переслать на сервер новый сертификат (и ключ, если надо) и записать их в указанные при старте сервера файлы. При использовании этой команды нужно сформировать файл с новым сертификатом и, при необходимости, ключом, в формате PEM (используете cat для объединения сертификата и ключа в один файл) и указать этот файл в параметре value. Если в файле не будет указан закрытый ключ, то сервером будет использован текущий (тот, что был указан при запуске). Данная команда также изменит файлы сертификата и ключа (если он указан), указанные при старте сервера, на новые значения.
svacer admin --ssl --host example.com --user admin --password admin --scope server:config --id ssl.cert --action update --value svacer.pem
Некоторое время после обновления сервер может использовать старые сертификаты для уже установленных соединений, при этом обновление страницы не помогает, нужно дождаться пока сервер не разорвет соединение на своей стороне ввиду отсутствия активности клиента.

Выбор сетевых интерфейсов и портов сервера

  • По умолчанию web-сервер запускается на всех сетевых интерфейсах, на порту 8080 (0.0.0.0:8080). Для указания конкретного сетевого интерфейса можно использовать опцию --listen <network interface>, для указания другого порта: --port <port_number>.
  • Аналогично для grpc-сервера: по умолчанию — 0.0.0.0:3002, для выбора конкретного интерфейса: --listen-grpc <network_interface>, для указания другого порта: --grpc <port_number>.

Пример:

 svacer server --listen 127.0.0.1 --port 9090 --listen-grpc 127.0.0.1 --grpc 3004