light_control

Описание

Многопользовательский веб-сервис для управления офисными лампами через контроллеры Wirenboard по протоколу MQTT

Требования

• Ubuntu >=16.04 (Debian)
• python-full >= 3.9.2

При чистой установке

• php-fpm php-sqlite3 >= 7.4
• libapache2-mod-php >= 7.4 (только для Apache)

При установке через Docker

• Docker >=20.10
• Docker-compose >= 1.29

Как это работает

Веб-приложение позволяет войти/зарегистрироваться пользователю, получать данные с ламп и управлять их режимами. На главной странице размещены основные элементы управления, а также в боковом меню можно посмотреть план помещения с расположенными в нем лампами.

Для хранения пользователей и их действий используется БД SQLite. Доступ администратора к БД осуществляется через Adminer, который также позволяет экспортировать данные из БД

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

Предусмотрено два варианта:

• Чистая установка (Apache или Nginx)
• Установка через Docker

Скопируйте или переименуйте файл .env.example в .env для того, чтобы приложения/установочные скрипты смогли прочитать из него данные.

Чистая установка (bare install)

Данная установка производится напрямую в ОС (Ubuntu/Debian).

• в .env файле в переменной LIGHT_CONTROL_PORT укажите порт на котором будет работать веб-приложение и куда будет проксировать трафик Apache (например 8000)

• в .env файле в переменной ROOT_PATH укажите путь до веб-приложения, через который Apache будет проксировать трафик. Важно: чтобы в конце и в начале пути были знаки / (например /light-control/). Важно: в данном варианте установки не назначайте данной переменной /, т.к. этот путь для веб-приложения перекроет путь до Adminer

• для указания остальных переменных в .env читайте описание в разделе ниже

• cкрипты установки и удаления для Nginx и Apache находятся в директории bare_install. Перейдите в соответствующую подпапку и запустите install.sh, который произведет необходимую настройку сервера, создание папок для БД и сгенерирует конфиги сайта для приложения. После успешного завершения скрипта, вставьте содержимое файла .nginx.site / .apache.site в файл настроек сайта вашего сервера, после чего перезапустите сервер. Особенность: некоторые уже имеющиеся настройки сервера могут "сломать" сгенерированные конфиги, что приведет к некорректной работе сайта (например, сломанные прокси-пути к статическим файлам)

• для запуска и остановки самого веб-приложения существует два подхода:

  • systemd: для ос с systemd и systemctl можно воспользоваться скриптом install.sh в директории bare_install/systemd, который установит веб-приложение в качестве демона light-control.service. Веб-приложение будет автоматически запускаться при запуске ОС. Управлять демоном веб-приложения можно через systemctl

  • nohup: в директории bare_install находятся два скрипта: server_start.sh и server_stop.sh. Скрипт server_start.sh запускает веб-приложение с помощью nohup и создает файл uvicorn.pid с PID процесса приложения для того, чтобы server_stop.sh смог его завершить

Установка через Docker

Данная установка запускает веб-приложение и Adminer в двух отдельных контейнерах с помощью docker-compose.

• в .env файле в переменной LIGHT_CONTROL_PORT укажите порт на котором будет работать веб-приложение (например 8000)

• в .env файле в переменной ADMINER_PORT укажите порт на котором будет работать Adminer (например 10000)

• в .env файле в переменной ROOT_PATH оставьте значение по умолчанию (/)

• для указания остальных переменных в .env читайте описание в разделе ниже

• запустите команду docker-compose up -d, после ее выполнения веб-приложение и Adminer будут доступны на хостовой ОС по адресу 0.0.0.0 на тех портах, которые были указаны в переменных LIGHT_CONTROL_PORT и ADMINER_PORT

• для отключения обоих контейнеров введите команду docker-compose down. Важно: при данной команде файл БД не удаляется

Особенность: в данном варианте установки, если ваш MQTT брокер развернут на хостовой системе, то в .env файле в переменной MQTT_HOST нужно указать host.docker.internal

Разработка

Во время разработки, для установки и управления зависимостями рекомендуется использовать пакетный менеджер PDM не ниже версии 2.5. Версии зависимостей рекомендуется указывать с помощью спецификаторов совместимости по хотфиксовой версии (например, fastapi~=0.95.1, т.е. обновления будут следовать только по хотфиксовым версиям).

Для локального запуска веб-приложения во время разработки рекомендуется назначить переменной LOG_LEVEL значение INFO или DEBUG, а ROOT_PATH оставить по умолчанию.

Команда для локального запуска:

uvicorn app:app --host 0.0.0.0 --port 8000

Важно: обратите внимание, что при локальном запуске значение переменной LIGHT_CONTROL_PORT игнорируется и нужно его задать самому, как в команде выше (также как и хост).

Описание .env файла:

Для доступа к БД

• DBMS_ADMINER_PASSWORD - пароль для подключения к БД через Adminer

• DBMS_ACCESS_PATH/DBMS_NAME - путь до БД, который указывается в Adminer

Для чистой установки

• LIGHT_CONTROL_PORT - задает порт на котором поднимается/доступно веб-приложение

• DBMS_ACCESS_PATH - по данному пути находится символическая ссылка на сам файл БД, который находится в DBMS_PATH. Необходимо для доступа к БД через Adminer.

Для установки через Docker

• LIGHT_CONTROL_PORT - задает порт на котором поднимается/доступно веб-приложение

• ADMINER_PORT - задает порт на котором поднимается/доступен Adminer

• DBMS_ACCESS_PATH - по данному пути находится путь проброса volume с БД в контейнер с Adminer.

Для приложения

• LOG_LEVEL - задает уровень логирования веб-приложения. Возможные значения: DEBUG, INFO, WARNING, ERROR, CRITICAL. По умолчанию: WARNING.

• LOG_FILE_PATH - задает путь до файла с логами веб-приложения. По умолчанию: volumes/logs/logs.log

• ROOT_PATH - задает корень пути до веб-приложения, требует изменения только во время чистой установки для соблюдения проксирования трафика через Apache или Nginx. Важно: путь должен обязательно оканчиваться на /. По умолчанию: /

• DBMS_NAME - имя файла БД. По умолчанию: light_data.db3

• DBMS_PATH - путь до файла БД. По умолчанию: volumes/dbms

• DBMS_ADMINER_PASSWORD - пароль для подключения к БД через Adminer

• JWT_SECRET_KEY - 32-значный ключ для цифровой подписи JWT. Получить данный ключ можно командой openssl rand -hex 32

• JWT_TOKEN_EXPIRE_DAYS - срок истечения JWT в днях (aka срок жизни сессии пользователя после авторизации). По умолчанию: 30

• LAMPS_INIT_TEMPERATURE - цветовая температура ламп, которая задается при включении сервиса. По умолчанию: 4500

• LAMPS_INIT_BRIGHTNESS - яркость ламп, которая задается при включении сервиса. По умолчанию: 100

• MQTT_HOST - адрес MQTT брокера

• MQTT_PORT - порт для подключения к MQTT брокеру. По умолчанию: 1883

• MQTT_TOPIC_LAMP_PATTERN - шаблон топика ждя ламп, в котором обязательно должны содержаться две переменные {id} и {measure}, которые отвечают за идентификатор лампы и тип характеристики (цветовая температура и яркость). Пример шаблона в .env.example файле. Важно: шаблон должен быть обособлен в двойные кавычки

• MQTT_LAMP_IDS - список идентификаторов ламп. Пример в .env.example файле. Важно: записываются через запятую без пробелов, каждое значение в двойных кавычках и все это в квадратных скобках

• MQTT_LAMP_TEMP_MEASURE - обозначение характеристики цветовой температуры в MQTT топике лампы ({measure})

• MQTT_LAMP_BRIGHT_MEASURE - обозначение характеристики яркости в MQTT топике лампы ({measure})