Help:Installation

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

Для работы сервера необходим 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.

На Astra Linux необходимо в файле /etc/parsec/mswitch.conf установить параметр zero_if_notfound: yes, иначе при запуске Svacer будет ошибка подключения к БД вида

 error obtaining MAC configuration for user "svace" (SQLSTATE 57P03)

После создания БД и настройки конфигурации 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')

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

Настройка TLS

Svacer может быть сконфигурирован для поддержки TLS несколькими способами. Первый способ — использовать reverse proxy с поддержкой HTTPS и проксированием в Svacer по HTTP, второй — запуск Svacer с непосредственной поддержкой TLS (нативная поддержка).

Reverse proxy (первый способ)

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

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
    
    # svacer HTTP URL
    ProxyPass / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/

    # 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/
    RewriteEngine on
    RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
    RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
    RewriteRule /api/ws/(.*) ws://127.0.0.1:8080%{REQUEST_URI} [P]

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

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

 systemctl restart apache2

Нативно (второй способ)

Данный способ позволяет обеспечить безопасную передачу данных как по протоколу HTTPS, так и по протоколу gRPC. Если сервер запускается с поддержкой TLS, то эта опция относится как к протоколу HTTPS, так и протоколу gRPC. По умолчанию сервер запускается без поддержки TLS, при этом в логах отображается информация об этом.

TLS for REST and gRPC DISABLED

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

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

При этом ключ должен быть в незашифрованном виде. Права доступа к файлу должны быть 0600. В файле сертификата можно указывать цепочку сертификатов. В этом случае сервер, при подключении клиента, будет возвращать всю цепочку. Первым сертификатом в цепочке всегда должен идти сертификат сервера Svacer. Формат файла — 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