Збірка Fledge

Давайте розпочнемо! У цьому розділі ми побачимо, де знайти і як створити, встановити та запустити Fledge вперше.

Платформи Fledge

Завдяки використанню стандартних бібліотек Fledge може працювати на великій кількості платформ і операційних середовищ, але його основною метою є дистрибутиви Linux. Наше тестове середовище включає Ubuntu 18.04 LTS, Ubuntu 20.04 LTS і Raspbian, але ми встановили та перевірили Fledge на інших дистрибутивах Linux. Окрім вбудованої підтримки, Fledge також може працювати на віртуальних машинах, контейнерах Docker і LXC.

Вимоги

Для створення Fledge потрібно інсталювати низку пакетів програмного забезпечення та бібліотек, процес інсталяції яких спрощено та автоматизовано для всіх підтримуваних наразі платформ. Можна запустити єдиний скрипт requirements.sh, який інсталює всі пакети, необхідні для створення та запуску Fledge.

Збірка Fledge

У цьому розділі ми опишемо, як зібрати Fledge на будь-якій із підтримуваних платформ. Якщо ви не знайомі з Linux і не хочете створювати Fledge із вихідного коду, ви можете завантажити готовий пакет (список пакетів доступний тут).

Отримання вихідного коду

Fledge доступний на GitHub. Посилання на репозиторій — . Щоб клонувати код у репозиторії, введіть:

$ git clone https://github.com/fledge-iot/fledge.git
Cloning into 'fledge'...
remote: Enumerating objects: 83394, done.
remote: Counting objects: 100% (2093/2093), done.
remote: Compressing objects: 100% (903/903), done.
remote: Total 83394 (delta 1349), reused 1840 (delta 1161), pack-reused 81301
Receiving objects: 100% (83394/83394), 34.85 MiB | 7.38 MiB/s, done.
Resolving deltas: 100% (55599/55599), done.

Тепер код має бути завантажено на вашу машину в каталог під назвою fledge. Ім'я каталогу сховища - fledge:

$ ls -l fledge
total 228
drwxrwxr-x  7 fledge fledge   4096 Aug 26 11:20 C
-rw-rw-r--  1 fledge fledge   1659 Aug 26 11:20 CMakeLists.txt
drwxrwxr-x  2 fledge fledge   4096 Aug 26 11:20 contrib
-rw-rw-r--  1 fledge fledge   4786 Aug 26 11:20 CONTRIBUTING.md
drwxrwxr-x  4 fledge fledge   4096 Aug 26 11:20 data
drwxrwxr-x  2 fledge fledge   4096 Aug 26 11:20 dco-signoffs
drwxrwxr-x 10 fledge fledge   4096 Aug 26 11:20 docs
-rw-rw-r--  1 fledge fledge 108680 Aug 26 11:20 doxy.config
drwxrwxr-x  3 fledge fledge   4096 Aug 26 11:20 examples
drwxrwxr-x  4 fledge fledge   4096 Aug 26 11:20 extras
-rw-rw-r--  1 fledge fledge  11346 Aug 26 11:20 LICENSE
-rw-rw-r--  1 fledge fledge  24216 Aug 26 11:20 Makefile
-rwxrwxr-x  1 fledge fledge    310 Aug 26 11:20 mkversion
drwxrwxr-x  4 fledge fledge   4096 Aug 26 11:20 python
-rw-rw-r--  1 fledge fledge   9292 Aug 26 11:20 README.rst
-rwxrwxr-x  1 fledge fledge   8177 Aug 26 11:20 requirements.sh
drwxrwxr-x  8 fledge fledge   4096 Aug 26 11:20 scripts
drwxrwxr-x  4 fledge fledge   4096 Aug 26 11:20 tests
drwxrwxr-x  3 fledge fledge   4096 Aug 26 11:20 tests-manual
-rwxrwxr-x  1 fledge fledge     38 Aug 26 11:20 VERSION

Вибір правильної версії

Сховище git, створене на вашій локальній машині, створює кілька гілок. Більш конкретно:

Гілка main є останньою, стабільною версією. Ви повинні використовувати цю гілку, якщо ви зацікавлені у використанні Fledge з функціями та виправленнями останнього випуску.
Гілка develop є поточною робочою гілкою, яку використовують наші розробники. Гілка містить найновішу версію та функції, але вона може бути нестабільною та в коді можуть бути проблеми. Ви можете розглянути можливість використання цієї гілки, якщо вам цікаво побачити одну з останніх функцій, над якою ми працюємо, але вам не слід використовувати цю гілку у виробництві.
Гілки з версіями majorID.minorID або majorID.minorID.patchID, наприклад 1.0 або 1.4.2, містять код цієї конкретної версії. Ви можете скористатися однією з цих гілок, якщо вам потрібно перевірити код, який використовується в цих версіях.
Гілки з іменем FOGL-XXXX, де «XXXX» — порядковий номер, є робочими гілками, які використовуються розробниками та учасниками для додавання функцій, вирішення проблем, зміни та випуску коду та документації Fledge. Ці гілки є безкоштовними для вас, щоб ви могли побачити та дізнатися про роботу учасників.

Зауважте, що гілкою за замовчуванням є develop.

Після того, як ви клонували проект Fledge, щоб перевірити доступні гілки, скористайтеся командою git branch:

$ pwd
/home/ubuntu
$ cd fledge
$ git branch --all
* develop
remotes/origin/1.0
...
remotes/origin/FOGL-822
remotes/origin/FOGL-823
remotes/origin/HEAD -> origin/develop
...
remotes/origin/develop
remotes/origin/main

Якщо ви хочете використовувати останню стабільну версію, скористайтеся командою git checkout, щоб вибрати гілку master:

$ git checkout main
Branch main set up to track remote branch main from origin.
Switched to a new branch 'main'

Ви завжди можете скористатися командою git status, щоб перевірити гілку, яку ви обрали.

Зборка Fledge

Тепер ви готові зібрати свій перший проект Fledge.

Перейдіть до каталогу проекту fledge
Завантажте вимоги, необхідні для зборки Fledge, ввівши текст

$ sudo ./requirements.sh
[sudo] password for john:
Platform is Ubuntu, Version: 18.04
apt 1.6.14 (amd64)
Reading package lists...
Building dependency tree...
...

Надрукуйте команду make і дозвольте магії здійснитися.

$ make
Building Fledge version X.X., DB schema X
scripts/certificates "fledge" "365"
Creating a self signed SSL certificate ...
Certificates created successfully, and placed in data/etc/certs
scripts/auth_certificates ca "ca" "365"
...
Successfully installed aiohttp-3.8.1 aiohttp-cors-0.7.0 aiosignal-1.2.0 async-timeout-4.0.2 asynctest-0.13.0 attrs-22.1.0 cchardet-2.1.4 certifi-2022.6.15 charset-normalizer-2.1.1 frozenlist-1.2.0 idna-3.3 idna-ssl-1.1.0 ifaddr-0.2.0 multidict-5.2.0 pyjq-2.3.1 pyjwt-1.6.4 requests-2.27.1 requests-toolbelt-0.9.1 six-1.16.0 typing-extensions-4.1.1 urllib3-1.26.12 yarl-1.7.2 zeroconf-0.27.0
$

ежно від версії Ubuntu або іншого дистрибутива Linux, який ви використовуєте, ви могли виявити деякі проблеми. Наприклад, у компіляторі GCC є помилка, яка викликає попередження за певних обставин. Результат збирання буде приблизно таким:

/home/ubuntu/Fledge/C/services/storage/storage.cpp:97:14: warning: ignoring return value of ‘int dup(int)’, declared with attribute warn_unused_result [-Wunused-result]
  (void)dup(0);     // stdout GCC bug 66425 produces warning
              ^
/home/ubuntu/Fledge/C/services/storage/storage.cpp:98:14: warning: ignoring return value of ‘int dup(int)’, declared with attribute warn_unused_result [-Wunused-result]
  (void)dup(0);     // stderr GCC bug 66425 produces warning
              ^

Помилка задокументована в . Для нашого проекту ви повинні ігнорувати це.

Інша проблема пов’язана з версією pip (точніше pip3), менеджера пакетів Python. Якщо ви бачите це попередження в середині виведення збірки:

/usr/lib/python3.6/distutils/dist.py:261: UserWarning: Unknown distribution option: 'python_requires'
  warnings.warn(msg)

...і цей вивід наприкінці процесу збирання:

You are using pip version 8.1.1, however version 9.0.1 is available.
You should consider upgrading via the 'pip install --upgrade pip' command.

У цьому випадку вам потрібно оновити програмне забезпечення pip для Python3:

$ sudo pip3 install --upgrade pip
Collecting pip
  Downloading pip-9.0.1-py2.py3-none-any.whl (1.3MB)
    100% |████████████████████████████████| 1.3MB 1.1MB/s
Installing collected packages: pip
Successfully installed pip-9.0.1

У цей момент виконайте команду make знову, і попередження Python має зникнути.

Тестування Fledge із середовища збирання

Якщо ви прагнете негайно випробувати Fledge, ви можете це зробити! Усе, що вам потрібно зробити, це встановити змінну середовища FLEDGE_ROOT, і все готово. Залишайтеся в каталозі проекту Fledge, встановіть змінну середовища зі шляхом до каталогу Fledge і запустіть fledge командою fledge start:

$ pwd
/home/ubuntu/fledge

$ export FLEDGE_ROOT=/home/ubuntu/fledge

$ ./scripts/fledge start
Starting Fledge vX.X.....
Fledge started.

Ви можете перевірити статус Fledge за допомогою команди fledge status. Протягом кількох секунд ви можете побачити запуск сервісу, а потім вона покаже статус сервісів і завдань Fledge:

$ ./scripts/fledge status
Fledge starting.

$ scripts/fledge status
Fledge vX.X.X running.
Fledge Uptime:  9065 seconds.
Fledge records: 86299 read, 86851 sent, 0 purged.
Fledge does not require authentication.
=== Fledge services:
fledge.services.core
fledge.services.storage --address=0.0.0.0 --port=42583
fledge.services.south --port=42583 --address=127.0.0.1 --name=Sine
fledge.services.notification --port=42583 --address=127.0.0.1 --name=Fledge Notifications
=== Fledge tasks:
fledge.tasks.purge --port=42583 --address=127.0.0.1 --name=purge
tasks/sending_process --port=42583 --address=127.0.0.1 --name=PI Server

Якщо вам цікаво побачити належний вивід від Fledge, ви можете запитати мікросервіс Core за допомогою REST API:

$ curl -s http://localhost:8081/fledge/ping ; echo
{"uptime": 10480, "dataRead": 0, "dataSent": 0, "dataPurged": 0, "authenticationOptional": true, "serviceName": "Fledge", "hostName": "fledge", "ipAddresses": ["x.x.x.x", "x:x:x:x:x:x:x:x"], "health": "green", "safeMode": false}

$ curl -s http://localhost:8081/fledge/statistics ; echo
[{"key": "BUFFERED", "description": "Readings currently in the Fledge buffer", "value": 0}, {"key": "DISCARDED", "description": "Readings discarded by the South Service before being  placed in the buffer. This may be due to an error in the readings themselves.", "value": 0}, {"key": "PURGED", "description": "Readings removed from the buffer by the purge process", "value": 0}, {"key": "READINGS", "description": "Readings received by Fledge", "value": 0}, {"key": "UNSENT", "description": "Readings filtered out in the send process", "value": 0}, {"key": "UNSNPURGED", "description": "Readings that were purged from the buffer before being sent", "value": 0}]

Щиро вітаю! Ви встановили та протестували Fledge! Якщо ви хочете піти далі (і зробити вивід REST API більш читабельним), завантажте редактор JSON jq і передайте в нього вивід команди curl:

$ sudo apt install jq

$ curl -s http://localhost:8081/fledge/statistics | jq

Вивід консолі

[
  {
    "key": "BUFFERED",
    "description": "Readings currently in the Fledge buffer",
    "value": 0
  },
  {
    "key": "DISCARDED",
    "description": "Readings discarded by the South Service before being  placed in the buffer. This may be due to an error in the readings themselves.",
    "value": 0
  },
  {
    "key": "PURGED",
    "description": "Readings removed from the buffer by the purge process",
    "value": 0
  },
  {
    "key": "READINGS",
    "description": "Readings received by Fledge",
    "value": 0
  },
  {
    "key": "UNSENT",
    "description": "Readings filtered out in the send process",
    "value": 0
  },
  {
    "key": "UNSNPURGED",
    "description": "Readings that were purged from the buffer before being sent",
    "value": 0
  }
]

Тепер я хочу зупинити Fledge!

Легко, ви вивчили fledge start і fledge status, просто введіть fledge stop:

$ scripts/fledge stop
Stopping Fledge.........
Fledge stopped.

Як наступний крок, давайте встановимо Fledge!

Додаток: Налаштування бази даних PostgreSQL

Якщо ви збираєтеся використовувати базу даних PostgreSQL як механізм зберігання, переконайтеся, що PostgreSQL встановлено та працює правильно:

# sudo systemctl status postgresql
● postgresql.service - PostgreSQL RDBMS
   Loaded: loaded (/lib/systemd/system/postgresql.service; enabled; vendor preset: enabled)
   Active: active (exited) since Fri 2017-12-08 15:56:07 GMT; 15min ago
 Main PID: 14572 (code=exited, status=0/SUCCESS)
   CGroup: /system.slice/postgresql.service

Dec 08 15:56:07 ubuntu systemd[1]: Starting PostgreSQL RDBMS...
Dec 08 15:56:07 ubuntu systemd[1]: Started PostgreSQL RDBMS.
Dec 08 15:56:11 ubuntu systemd[1]: Started PostgreSQL RDBMS.

Postgres processes:

$ ps -ef | grep postgres
postgres 14806     1  0 15:56 ?        00:00:00 /usr/lib/postgresql/9.5/bin/postgres -D /var/lib/postgresql/9.5/main -c config_file=/etc/postgresql/9.5/main/postgresql.conf
postgres 14808 14806  0 15:56 ?        00:00:00 postgres: checkpointer process
postgres 14809 14806  0 15:56 ?        00:00:00 postgres: writer process
postgres 14810 14806  0 15:56 ?        00:00:00 postgres: wal writer process
postgres 14811 14806  0 15:56 ?        00:00:00 postgres: autovacuum launcher process
postgres 14812 14806  0 15:56 ?        00:00:00 postgres: stats collector process
ubuntu   15198  1225  0 17:22 pts/0    00:00:00 grep --color=auto postgres

На момент публікації цієї сторінки для Ubuntu 18.04 доступна версія PostgreSQL 13. Інші версії PostgreSQL, наприклад від 9.6 до новішої версії, працюють чудово. Коли ви інсталюєте пакет Ubuntu, PostreSQL налаштовано на однорангову автентифікацію, тобто користувач бази даних має збігатися з користувачем Linux. Інші пакети можуть відрізнятися. Ви можете швидко перевірити режим автентифікації, встановлений у файлі pg_hba.conf. Файл знаходиться в тому самому каталозі, що й файл postgresql.conf, який ви можете побачити як результат команди ps, показаної вище, у нашому випадку /etc/postgresql/9.5/main:

$ sudo grep '^local' /etc/postgresql/9.5/main/pg_hba.conf
local   all             postgres                                peer
local   all             all                                     peer

Процедура встановлення також створює користувача Linux postgres. Щоб перевірити, чи все налаштовано правильно, запустіть утиліту psql від імені користувача sudo:

$ sudo -u postgres psql -l
                                  List of databases
   Name    |  Owner   | Encoding |   Collate   |    Ctype    |   Access privileges
-----------+----------+----------+-------------+-------------+-----------------------
 postgres  | postgres | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 |
 template0 | postgres | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 | =c/postgres          +
           |          |          |             |             | postgres=CTc/postgres
 template1 | postgres | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 | =c/postgres          +
           |          |          |             |             | postgres=CTc/postgres
(3 rows)

Кодування та сортування можуть відрізнятися залежно від вибору, зробленого під час встановлення операційної системи. Перш ніж продовжити, ви повинні створити користувача PostgreSQL, який відповідає вашому користувачу Linux. Припустимо, що ваш користувач fledge_user, введіть:

$ sudo -u postgres createuser -d <fledge_user>

Аргумент -d важливий, оскільки користувачеві потрібно буде створити базу даних Fledge.

Більш загальною командою що визначить змінну поточного користувача є:

$ sudo -u postgres createuser -d $(whoami)

Нарешті, тепер ви зможете побачити список доступних баз даних вашого поточного користувача:

$ psql -l
                                  List of databases
   Name    |  Owner   | Encoding |   Collate   |    Ctype    |   Access privileges
-----------+----------+----------+-------------+-------------+-----------------------
 postgres  | postgres | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 |
 template0 | postgres | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 | =c/postgres          +
           |          |          |             |             | postgres=CTc/postgres
 template1 | postgres | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 | =c/postgres          +
           |          |          |             |             | postgres=CTc/postgres
(3 rows)

Платформи Fledge​

Вимоги​

Збірка Fledge​

Отримання вихідного коду​

Вибір правильної версії​

Зборка Fledge​

Тестування Fledge із середовища збирання​

Тепер я хочу зупинити Fledge!​

Додаток: Налаштування бази даних PostgreSQL​

Платформи Fledge

Вимоги

Збірка Fledge

Отримання вихідного коду

Вибір правильної версії

Зборка Fledge

Тестування Fledge із середовища збирання

Тепер я хочу зупинити Fledge!

Додаток: Налаштування бази даних PostgreSQL