====== Аннотация ======
В данном программном документе приведено руководство системного программиста по установке и настройке системы накопления и управления данными сети измерений, предназначенной для сохранения и предоставления данных по приборам на кафедре К3

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

====== Структура системы ======
Система состоит из трех основных компонентов: серверная часть, клиентская часть и базы данных. Клиент отправляет запросы серверу приложения, тот, в свою очередь, обращается при необходимости к базе и дает ответ клиенту.

====== Настройка системы ======
Настройка системы будет рассматриваться на примере операционной системы Debian.
===== 1. Установка Docker =====
Обновите пакеты.
<code>apt-get update</code>

Установите необходимые пакеты для работы с HTTPS-соединениями и загрузки файлов.
<code>apt-get install ca-certificates curl</code>

Создайте директорию /etc/apt/keyrings с правами доступа 0755.
<code>install -m 0755 -d /etc/apt/keyrings</code>

Загрузите GPG-ключ Docker из официального репозитория и сохраните его в файле /etc/apt/keyrings/docker.asc.
<code>curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc</code>

Предоставьте права на чтение файла GPG-ключа всем пользователям.
<code>chmod a+r /etc/apt/keyrings/docker.asc</code>

Добавьте запись в файл /etc/apt/sources.list.d/docker.list, которая указывает на репозиторий Docker для Debian. Эта запись содержит информацию об архитектуре системы и пути к GPG-ключу.

<code>echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null</code>
  
Обновите список доступных пакетов с учетом добавленного репозитория Docker.
<code>apt-get update</code>

Установите Docker.
<code>apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin</code>

Для того, чтобы убедиться, что все работает корректно, запустите тестовый контейнер.
<code>docker run hello-world</code>

Если необходимо установить Docker на какую-либо другую операционную систему, то посмотрите официальную документацию: https://docs.docker.com/

===== 2. Развертывание приложения =====
После успешной установки Docker, можно разворачивать приложение. Для того, чтобы развернуть приложение необходимо перейти в папку проекта. Из самого корня папки проекта необходимо выполнить команду:
<code>docker-compose up</code>

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

На этом этапе приложение полностью функционирует и готово к работе.

====== Проверка системы ======
Для проверки того, что у нас функционирует все контейнеры и системы готова достаточно выполнить команду ''docker container ls''. Мы должны увидеть три контейнеры: app - наше приложение, influxdb - контейнер базы данных influxdb и postgresdb - контейнер базы данных postgresql.

====== Конфигурация системы ======
Приложение развернуто при помощи Docker, поэтому оно имеет файл конфигурации Docker-контейнеров. Этот файл называется docker-compose.yaml. Он находится в корне проекта. За счет него разворачиваются контейнеры с определенными настройками, в определенной последовательности.
<file yaml docker-compose.yaml>
services:
  app:
    container_name: app
    image: app
    build: 
      dockerfile: MeasurementSystem.Server/Dockerfile
    ports:
      - '3500:8080'
    depends_on:
      - influxdb
      - postgresdb
  influxdb:
    container_name: influxdb
    image: influxdb:2
    ports:
      - '8086:8086'
    volumes:
      - ./InfluxDB/db:/var/lib/influxdb2
      - ./InfluxDB/configs:/etc/influxdb2
      - ./InfluxDB/backup:/backup
    environment:
      - DOCKER_INFLUXDB_DB=influxdb
      - DOCKER_INFLUXDB_INIT_MODE=setup
      - DOCKER_INFLUXDB_INIT_USERNAME=*Имя пользователя*
      - DOCKER_INFLUXDB_INIT_PASSWORD=*Пароль*
      - DOCKER_INFLUXDB_INIT_ORG=org
      - DOCKER_INFLUXDB_INIT_BUCKET=init-bucket
  postgresdb:
    container_name: postgresdb
    image: postgres:latest
    ports:
      - '5432:5432'
    volumes:
      - ./PostgresDB/db:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=postgresdb
      - POSTGRES_USER=*Имя пользователя*
      - POSTGRES_PASSWORD=*Пароль*
</file>
Самым первым шагом в написании этого файла является определение контейнеров приложения. Это приложение многоконтейнерное, поэтому важно правильно сконфигурировать каждый контейнер и задать правильную последовательность запуска. 

Ключевым словом, после которого можно определять контейнеры приложения, является «services». После него идут наши собственные названия контейнеров. В Docker контейнер называется сервисом, поэтому далее так и будем называть это сервисами.

**Сервис app**

Сервис app использует образ Docker, построенный из Dockerfile, расположенного в директории MeasurementSystem.Server. Он связывает порт 3500 хоста с портом 8080 контейнера, позволяя получить доступ к приложению снаружи контейнера. Сервис зависит от сервисов influxdb и postgresdb, что означает, что он будет запущен только после запуска этих зависимых сервисов.

**Сервис influxdb**

Сервис influxdb использует образ influxdb:latest, который представляет собой последнюю версию InfluxDB - системы управления временными рядами данных. Он связывает порт 8086 хоста с портом 8086 контейнера, предоставляя доступ к API InfluxDB снаружи контейнера. Сервис использует несколько томов для постоянного хранения данных и конфигурации InfluxDB:
  * ./InfluxDB/db:/var/lib/influxdb2 – монтирует локальную директорию ./InfluxDB/db в качестве хранилища данных InfluxDB внутри контейнера.
  * ./InfluxDB/configs:/etc/influxdb2 – монтирует локальную директорию ./InfluxDB/configs в качестве хранилища конфигурационных файлов InfluxDB внутри контейнера.
  * ./InfluxDB/backup:/backup – монтирует локальную директорию ./InfluxDB/backup в качестве хранилища резервных копий внутри контейнера.
То есть эти папки можно найти локально в приложении.

Сервис также определяет несколько переменных окружения для инициализации InfluxDB при первом запуске: 
  * DOCKER_INFLUXDB_DB – создает базу данных influxdb.
  * DOCKER_INFLUXDB_INIT_MODE – указывает на режим инициализации.
  * DOCKER_INFLUXDB_INIT_USERNAME – устанавливает имя пользователя для аутентификации.
  * DOCKER_INFLUXDB_INIT_PASSWORD – устанавливает пароль для аутентификации.
  * DOCKER_INFLUXDB_INIT_ORG – создает организацию с именем org.
  * DOCKER_INFLUXDB_INIT_BUCKET – создает хранилище данных с именем init-bucket.

**Сервис postgresdb**

Сервис postgresdb использует образ postgres:latest, который представляет собой последнюю версию PostgreSQL - объектно-реляционной системы управления базами данных. Он связывает порт 5432 хоста с портом 5432 контейнера, предоставляя доступ к PostgreSQL снаружи контейнера. Сервис использует том ./PostgresDB/db для постоянного хранения данных PostgreSQL.

Сервис также определяет несколько переменных окружения для инициализации PostgreSQL при первом запуске:
  * POSTGRES_DB – создает базу данных postgresdb.
  * POSTGRES_USER – устанавливает имя пользователя для аутентификации.
  * POSTGRES_PASSWORD – устанавливает пароль для аутентификации.

====== Полезные команды для настройки и управления системой ======
<code>docker-compose up -d --no-deps --build app</code>
Описание команды:
  * ''docker-compose up'' запускает контейнеры, определенные в файле docker-compose.yml, в detached режиме (в фоне).
  * ''-d'' указывает, что контейнеры должны запускаться в detached режиме.
  * ''--no-deps'' указывает, что не нужно ожидать, пока все зависимости будут запущены. Контейнеры запускаются в порядке, указанном в файле docker-compose.yml.
  * ''--build'' указывает, что нужно собрать образы контейнеров заново, если они не существуют или не обновлены.
  * ''app'' указывает, что только контейнеры, определенные в секции app в файле docker-compose.yml, должны быть запущены.

В целом, эта команда запускает только контейнер app в файле docker-compose.yml, в detached режиме, не ожидая запуска всех зависимостей, и собирает образы заново, если они не существуют или не обновлены.

Команда может быть полезна тем, что app – это контейнер, который является основным нашим приложением и мы можем легко изменять код, не ломая базы данных.

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

<code>docker exec -it influxdb</code>
Описание команды:
  * ''docker exec'' запускает новый процесс в существующем контейнере.
  * ''-it'' указывает, что процесс должен запускаться в интерактивном режиме и должен иметь терминал.
  * ''influxdb'' указывает, что процесс должен запускаться в контейнере с именем influxdb. 

В целом, эта команда запускает интерактивный терминал в контейнере с именем influxdb, позволяя выполнять команды в этом контейнере.

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

Например, можно добавить к ней ''influx delete --bucket measurements-bucket --start 1970-01-01T00:00:00Z --stop 2024-05-23T00:00:00Z.''

<code>influx delete --bucket measurements-bucket --start 1970-01-01T00:00:00Z --stop 2024-05-23T00:00:00Z</code>
Описание команды:
  * ''influx delete'' указывает, что команда должна выполняться для удаления данных из базы данных InfluxDB.
  * ''--bucket measurements-bucket'' указывает, что команда должна выполняться для указанного бакета (bucket) с именем measurements-bucket.
  * ''--start 1970-01-01T00:00:00Z'' указывает, что команда должна начать удаление данных с указанной даты и времени (start).
  * ''--stop 2024-05-23T00:00:00Z'' указывает, что команда должна остановить удаление данных по указанной дате и времени (stop).

В целом, эта команда удаляет все данные из бакета measurements-bucket InfluxDB, начиная с даты 1 января 1970 года 00:00:00 UTC и заканчивая днём 23 мая 2024 года 00:00:00 UTC. 

Бакет для influxdb это, как таблица в реляционной базе данных. В нашем случае у нас используется один единственный бакет, который хранит все данные по приборам – measurements-bucket.

Также можно еще выполнить команду ''docker exec -it influxdb influx''. Она даст подсказку о всех командах для influxdb.

<code>docker exec -it postgresdb psql -U my-user postgresdb</code>
Описание команды:
  * ''docker exec'' запускает новый процесс в существующем контейнере.
  * ''-it'' указывает, что процесс должен запускаться в интерактивном режиме и должен иметь терминал.
  * ''postgresdb'' указывает, что процесс должен запускаться в контейнере с именем postgresdb.
  * ''psql'' указывает, что процесс должен запускаться с помощью команды psql, которая является клиентским инструментом для взаимодействия с базой данных PostgreSQL.
  * ''-U my-user'' указывает, что пользователь, с которым будет выполняться команда psql, имеет имя my-user.
  * ''postgresdb'' указывает, что команда psql должна выполняться для базы данных с именем postgresdb.

Эта команда запускает интерактивный терминал в контейнере postgresdb, позволяя выполнять команды psql для базы данных postgresdb под пользователем my-user.

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

====== ПРИЛОЖЕНИЕ 1 ======
===== Структура базы данных в InfluxDB =====
Во входных данных передаются два важных поля: Akey и Serial. На основе этих полей будет формироваться ключ. Они используются для формирования уникального ключа, который будет привязан к остальным полям, переданным в JSON пакете. Это позволяет создавать наборы данных, связанные с этим ключом, и хранить их в базе данных. 

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

Когда новое устройство вводится в систему, его данные попадают в базу, и для него формируется его модель.

===== Структура базы данных в PostgreSQL =====
{{:doc:2006:erd.png|}}
=== Рисунок 1. ===

В PostgreSQL будут находится 3 таблицы (рис. 1):
  * **DeviceInfos** – зарегистрированные приборы
  * **Users** – пользователи
  * **CalibrationItems** – калибровочные данные

**Таблица DeviceInfos**

Таблица DeviceInfos предназначена для хранения информации о зарегистрированных приборах в системе. Она содержит следующие поля:
  * **Id** (первичный ключ) – уникальный идентификатор прибора, который может быть использован для однозначной идентификации записи в таблице.
  * **Name** – название прибора, которое может быть полезно для пользователей при работе с системой.
  * **Serial** – серийный номер прибора, который может быть использован для отслеживания и идентификации конкретного физического устройства.
  * **AuthKey** – ключ аутентификации прибора в системе, который используется для подтверждения подлинности данных, передаваемых прибором.
  * **X** и **Y** – координаты расположения прибора, которые могут быть использованы для визуализации данных на карте или для анализа пространственных закономерностей. Location - название места, где расположен прибор, что может быть полезно для организации и управления приборами.
  * **IsDeleted** – флаг, указывающий, выведен ли прибор из системы. Это поле может быть использовано для логического удаления записей вместо физического удаления, что позволяет сохранять историю изменений.

**Таблица Users**

Таблица Users предназначена для хранения информации о пользователях системы. Она содержит следующие поля:
  * **Id** (первичный ключ) – уникальный идентификатор пользователя, который может быть использован для однозначной идентификации записи в таблице.
  * **Username** – имя пользователя, которое используется для входа в систему.
  * **Password** – пароль пользователя, который используется для аутентификации при входе в систему.

**Таблица CalibrationItems**

Таблица CalibrationItems предназначена для хранения калибровочных данных, связанных с приборами. Она содержит следующие поля:
  * **Id** (первичный ключ) – уникальный идентификатор калибровочной записи, который может быть использован для однозначной идентификации записи в таблице.
  * **AuthKey** – ключ аутентификации прибора, связанного с калибровочной записью. Это поле используется для связи калибровочных данных с конкретным прибором.
  * **Sensor** – название датчика, для которого применяются калибровочные коэффициенты. Это поле может быть полезно в случае, если прибор имеет несколько датчиков, требующих отдельной калибровки.
  * **CreationDate** – время создания калибровочной записи, которое может быть использовано для отслеживания истории калибровок и выявления возможных изменений.
  * **Coefficients** – массив коэффициентов, используемых для калибровки датчика. Это поле может содержать один или несколько коэффициентов, в зависимости от сложности калибровки.