Este dashboard foi provisionado para servir de base.
Use um painel Canvas no Grafana para montar a planta baixa.
URLs sugeridas de icones:
http://SEU_HOST:8088/static/grafana-icons/detector-smoke.svghttp://SEU_HOST:8088/static/grafana-icons/detector-heat.svghttp://SEU_HOST:8088/static/grafana-icons/module-input.svghttp://SEU_HOST:8088/static/grafana-icons/siren.svghttp://SEU_HOST:8088/static/grafana-icons/panel-nfs320.svgAssocie cada icone a itens do Zabbix via datasource Zabbix.
", + "mode": "html" + }, + "pluginVersion": "11.0.0", + "title": "Como usar", + "type": "text" + } + ], + "refresh": "30s", + "schemaVersion": 39, + "style": "dark", + "tags": [ + "vfire", + "floorplan", + "starter" + ], + "templating": { + "list": [] + }, + "time": { + "from": "now-6h", + "to": "now" + }, + "timepicker": {}, + "timezone": "", + "title": "V-Fire Floorplan Starter", + "uid": "vfire-floorplan", + "version": 1, + "weekStart": "" +} diff --git a/docs/GRAFANA_PLANTA_BAIXA.md b/docs/GRAFANA_PLANTA_BAIXA.md new file mode 100644 index 0000000..45b463f --- /dev/null +++ b/docs/GRAFANA_PLANTA_BAIXA.md @@ -0,0 +1,123 @@ +# Grafana e Planta Baixa + +Este guia cobre o uso do Grafana com o `V-Fire Monitor` para dashboards baseados em planta baixa. + +## Arquivos de apoio + +- [floorplan/floorplan-map.example.json](/mnt/c/Users/Syllas/Documents/V-Fire-Monitor/floorplan/floorplan-map.example.json) +- [tools/build_floorplan_bundle.py](/mnt/c/Users/Syllas/Documents/V-Fire-Monitor/tools/build_floorplan_bundle.py) + +## O que o instalador ja deixa pronto + +Na instalacao Debian 13: + +- plugin Zabbix do Grafana instalado +- datasource `Zabbix` provisionado +- dashboard inicial `V-Fire Floorplan Starter` +- icones SVG servidos pelo proprio `V-Fire Monitor` + +## URLs dos icones + +Substitua `SEU_HOST` pelo host do V-Fire Monitor. + +- `http://SEU_HOST:8088/static/grafana-icons/detector-smoke.svg` +- `http://SEU_HOST:8088/static/grafana-icons/detector-heat.svg` +- `http://SEU_HOST:8088/static/grafana-icons/module-input.svg` +- `http://SEU_HOST:8088/static/grafana-icons/siren.svg` +- `http://SEU_HOST:8088/static/grafana-icons/panel-nfs320.svg` + +## Dashboard inicial + +O instalador provisiona a pasta `V-Fire` no Grafana e um dashboard chamado: + +- `V-Fire Floorplan Starter` + +Esse dashboard serve como ponto de partida e lembra as URLs dos icones. + +## Formato versionavel da planta + +Para nao depender apenas de arrastar elementos manualmente no Grafana, o repositorio agora inclui um formato JSON de mapa de planta. + +Campos principais: + +- `title` +- `grafana_dashboard_uid` +- `background_image_url` +- `vfire_base_url` +- `zabbix_host` +- `items` + +Cada item descreve: + +- `id` +- `label` +- `item_key` +- `icon` +- `x` +- `y` +- `width` +- `height` +- `rotation` + +## Gerar bundle normalizado + +Exemplo: + +```bash +python3 tools/build_floorplan_bundle.py floorplan/floorplan-map.example.json +``` + +Isso gera um arquivo `.bundle.json` com: + +- URLs completas dos icones +- referencia do host do Zabbix +- referencias dos `item_key` +- coordenadas prontas para uso em futuras automacoes + +## Montando a planta baixa + +Abordagem recomendada: + +1. Abra o dashboard `V-Fire Floorplan Starter` +2. Crie ou edite um painel do tipo `Canvas` +3. Defina a imagem de fundo com a planta baixa do local +4. Adicione elementos visuais ou imagens representando cada ponto +5. Use os SVGs do `V-Fire Monitor` como base visual +6. Associe cada elemento ao item correspondente no datasource `Zabbix` + +## Como mapear itens + +Os itens que o app envia ao Zabbix seguem chaves como: + +- `notifier.status[NomeDoPonto]` +- `notifier.comm[NomeDoPonto]` +- `node.status[NomeDaCentral]` + +Os nomes dos pontos sao descobertos automaticamente a partir do monitoramento. + +## Estrategia recomendada de planta baixa + +- use a planta como imagem base +- posicione um icone por detector, modulo ou sirene +- use cor dinamica para refletir estado +- crie uma legenda simples com: + - normal + - incidente + - ack + - removido + - offline + +## Observacao pratica + +O instalador nao conhece a planta baixa real do cliente. + +Por isso, ele consegue deixar: + +- Grafana integrado +- datasource pronto +- dashboard inicial provisionado +- icones prontos +- formato versionavel da planta baixa +- bundle normalizado para futuras importacoes + +Mas o posicionamento exato dos elementos na planta baixa ainda precisa ser feito conforme o layout real da instalacao. diff --git a/docs/INSTALACAO_DEBIAN13.md b/docs/INSTALACAO_DEBIAN13.md new file mode 100644 index 0000000..8d11b3a --- /dev/null +++ b/docs/INSTALACAO_DEBIAN13.md @@ -0,0 +1,186 @@ +# Instalacao no Debian 13 + +Este guia cobre a instalacao da stack completa em uma maquina dedicada com: + +- `V-Fire Monitor` +- `PostgreSQL` +- `Zabbix Server + frontend` +- `Grafana` + +## Visao geral + +O instalador provisiona: + +- app em `/opt/vfire-monitor` +- dados persistentes em `/var/lib/vfire-monitor` +- logs do app em `/var/log/vfire-monitor/app.log` +- servico `systemd` do V-Fire Monitor +- template do Zabbix importado automaticamente +- host monitorado do Zabbix criado automaticamente +- datasource do Grafana apontando para o Zabbix +- dashboard inicial do Grafana provisionado + +Portas padrao: + +- `V-Fire Monitor`: `8088` +- `Zabbix frontend`: `8080` +- `Grafana`: `3000` + +## Requisitos + +- Debian 13 (`trixie`) +- acesso `root` +- internet para baixar pacotes +- portas livres para os servicos +- chave `VFM_LICENSE_MASTER_KEY` se a instalacao for de producao + +## Arquivos do instalador + +- [installer/install_debian13.sh](/mnt/c/Users/Syllas/Documents/V-Fire-Monitor/installer/install_debian13.sh) +- [installer/vfire-stack.env.example](/mnt/c/Users/Syllas/Documents/V-Fire-Monitor/installer/vfire-stack.env.example) + +## Passo 1: preparar configuracao + +Copie o arquivo de exemplo: + +```bash +cp installer/vfire-stack.env.example installer/vfire-stack.env +``` + +Edite `installer/vfire-stack.env`. + +Campos minimos que voce deve revisar: + +- `PUBLIC_HOSTNAME` +- `VFM_DEFAULT_PASSWORD` +- `VFM_LICENSE_MASTER_KEY` +- `ZABBIX_DB_PASSWORD` +- `ZABBIX_ADMIN_PASSWORD` +- `GRAFANA_ADMIN_PASSWORD` + +Se voce quiser testar sem chave mestre, pode usar: + +```env +ALLOW_LEGACY_LICENSE_KEY=1 +``` + +Isso e aceitavel para laboratorio. Para producao, use `VFM_LICENSE_MASTER_KEY`. + +## Passo 2: validar em dry-run + +Antes de instalar de verdade: + +```bash +chmod +x installer/install_debian13.sh +./installer/install_debian13.sh --dry-run ./installer/vfire-stack.env +``` + +Esse modo mostra as principais acoes sem executar a instalacao real. + +## Passo 3: executar a instalacao + +Como `root`: + +```bash +./installer/install_debian13.sh ./installer/vfire-stack.env +``` + +## Passo 4: validar os servicos + +Verifique: + +```bash +systemctl status vfire-monitor +systemctl status zabbix-server +systemctl status grafana-server +systemctl status nginx +``` + +Healthchecks HTTP: + +```bash +curl http://127.0.0.1:8088/healthz +curl -I http://127.0.0.1:8080/ +curl -I http://127.0.0.1:3000/login +``` + +## Passo 5: acessar os paineis + +Substitua `SEU_HOST` pelo hostname ou IP do servidor. + +V-Fire Monitor: + +```text +http://SEU_HOST:8088 +``` + +Zabbix: + +```text +http://SEU_HOST:8080 +``` + +Grafana: + +```text +http://SEU_HOST:3000 +``` + +## Credenciais + +O instalador grava um resumo em: + +```text +/root/vfire-stack-summary.txt +``` + +Esse arquivo inclui: + +- URL do V-Fire Monitor +- senha inicial do painel +- senha do Admin do Zabbix +- senha do admin do Grafana +- credenciais do banco do Zabbix +- nome do template do Zabbix +- nome do host do Zabbix + +## Estrutura final + +Arquivos principais apos instalar: + +- codigo: `/opt/vfire-monitor` +- dados: `/var/lib/vfire-monitor` +- ambiente: `/etc/default/vfire-monitor` +- servico: `/etc/systemd/system/vfire-monitor.service` + +## Operacoes comuns + +Reiniciar o app: + +```bash +systemctl restart vfire-monitor +``` + +Ver log do app: + +```bash +tail -f /var/log/vfire-monitor/app.log +``` + +Reiniciar Zabbix: + +```bash +systemctl restart zabbix-server nginx +``` + +Reiniciar Grafana: + +```bash +systemctl restart grafana-server +``` + +## Observacoes + +- o instalador foi desenhado para Debian 13 +- o app roda com Waitress, nao com o servidor de desenvolvimento do Flask +- o frontend do app usa assets locais, sem depender de CDN diff --git a/docs/LICENCIAMENTO.md b/docs/LICENCIAMENTO.md new file mode 100644 index 0000000..ccba9d3 --- /dev/null +++ b/docs/LICENCIAMENTO.md @@ -0,0 +1,113 @@ +# Licenciamento + +Este guia cobre a geracao e a instalacao de licenca do `V-Fire Monitor`. + +## Como o licenciamento funciona + +A licenca vincula: + +- `HWID` da maquina +- nome do cliente +- data de expiracao + +O serial e salvo em `license.key`. + +## Modos de chave + +Existem dois cenarios: + +1. `Chave mestre via VFM_LICENSE_MASTER_KEY` +2. `Chave legada embutida` + +Para producao, use `VFM_LICENSE_MASTER_KEY`. + +## Identificar o HWID + +Quando o app esta sem licenca, a tela inicial mostra o `Hardware ID`. + +Voce tambem pode coletar no proprio sistema onde o app esta rodando: + +```bash +python3 - <<'PY' +from vfire_monitor.core import get_hardware_id +print(get_hardware_id()) +PY +``` + +## Gerar o serial + +Uso por argumentos: + +```bash +python3 generator.py --hwid "HWID-DA-MAQUINA" --cliente "Nome do Cliente" --expira 2027-01-01 +``` + +Se `VFM_LICENSE_MASTER_KEY` estiver definida no ambiente, o gerador usa essa chave. + +Se nao estiver definida, ele usa a chave legada embutida. + +## Instalar a licenca pelo painel + +1. Abra o painel do `V-Fire Monitor` +2. Na tela de bloqueio, copie o `HWID` +3. Gere o serial +4. Cole o serial no campo de ativacao +5. Clique em `Ativar licenca` + +O backend valida: + +- serial +- HWID +- data de expiracao + +Se tudo estiver correto, o monitoramento e liberado. + +## Instalar a licenca manualmente no servidor + +Se voce ja tem o serial: + +```bash +cat > /var/lib/vfire-monitor/license.key <<'EOF' +SEU_SERIAL_AQUI +EOF + +chown vfire-monitor:vfire-monitor /var/lib/vfire-monitor/license.key +chmod 600 /var/lib/vfire-monitor/license.key +systemctl restart vfire-monitor +``` + +## Validar a licenca instalada + +Exemplo local: + +```bash +python3 - <<'PY' +from pathlib import Path +from vfire_monitor.core import LEGACY_LICENSE_KEY, LicenseService + +service = LicenseService(Path("license.key"), LEGACY_LICENSE_KEY) +status = service.verify() +print(status.valid, status.message, status.days_remaining, status.hardware_id) +PY +``` + +Se a instalacao de producao usar `VFM_LICENSE_MASTER_KEY`, a validacao deve usar a mesma chave mestre. + +## Quando a licenca falha + +Os erros mais comuns sao: + +- `Licenca ausente` +- `Serial invalido` +- `HWID incompativel` +- `Licenca expirada` + +## Boas praticas + +- use chave mestre por variavel de ambiente em producao +- nao distribua a chave legada em ambiente final +- mantenha backup de: + - `license.key` + - `app_secret.key` + - `config_nodes.json` + - `mapa_dispositivos.json` diff --git a/floorplan/floorplan-map.example.json b/floorplan/floorplan-map.example.json new file mode 100644 index 0000000..2913a44 --- /dev/null +++ b/floorplan/floorplan-map.example.json @@ -0,0 +1,39 @@ +{ + "title": "Planta Baixa - Pavimento 1", + "grafana_dashboard_uid": "vfire-floorplan-pav1", + "background_image_url": "https://example.local/planta/pavimento-1.png", + "vfire_base_url": "http://127.0.0.1:8088", + "zabbix_host": "NFS-320", + "items": [ + { + "id": "det-recepcao", + "label": "Detector Recepcao", + "item_key": "notifier.status[Detector Recepcao]", + "icon": "detector-smoke", + "x": 180, + "y": 120, + "width": 36, + "height": 36 + }, + { + "id": "mod-bomba", + "label": "Modulo Bomba Incendio", + "item_key": "notifier.status[Modulo Bomba Incendio]", + "icon": "module-input", + "x": 420, + "y": 260, + "width": 40, + "height": 40 + }, + { + "id": "sirene-p1", + "label": "Sirene Pavimento 1", + "item_key": "notifier.status[Modulo Sirene Pavimento 1]", + "icon": "siren", + "x": 680, + "y": 110, + "width": 42, + "height": 42 + } + ] +} diff --git a/generator.py b/generator.py index a5b63eb..55e1f98 100644 --- a/generator.py +++ b/generator.py @@ -1,58 +1,58 @@ -import argparse -import json -import os -from datetime import datetime - -from cryptography.fernet import Fernet - - -LEGACY_LICENSE_KEY = b"vS-C5Z_R1ST-Gf_K8_L9_Xo2-M1A3B5C7D9E1F2G3H4=" - - -def load_master_key() -> bytes: - env_key = os.getenv("VFM_LICENSE_MASTER_KEY") - if env_key: - return env_key.encode("utf-8") - return LEGACY_LICENSE_KEY - - -def parse_args(): - parser = argparse.ArgumentParser(description="Gerador de licenca do V-Fire Monitor") - parser.add_argument("--hwid", help="Hardware ID do cliente") - parser.add_argument("--cliente", help="Nome do cliente") - parser.add_argument("--expira", help="Data de expiracao no formato AAAA-MM-DD") - return parser.parse_args() - - -def ask_if_missing(value: str, prompt: str) -> str: - return value if value else input(prompt).strip() - - -def validate_expiration(date_text: str) -> str: - datetime.strptime(date_text, "%Y-%m-%d") - return date_text - - -def gerar_serial(hardware_id: str, cliente: str, data_expiracao: str) -> str: - fernet = Fernet(load_master_key()) - payload = {"h": hardware_id.strip(), "c": cliente.strip(), "e": validate_expiration(data_expiracao)} - return fernet.encrypt(json.dumps(payload, ensure_ascii=False).encode("utf-8")).decode("utf-8") - - -def main(): - args = parse_args() - - hardware_id = ask_if_missing(args.hwid, "Hardware ID do cliente: ") - cliente = ask_if_missing(args.cliente, "Nome do cliente: ") - expiracao = ask_if_missing(args.expira, "Validade (AAAA-MM-DD): ") - - if not hardware_id: - raise SystemExit("Hardware ID obrigatorio.") - if not cliente: - raise SystemExit("Nome do cliente obrigatorio.") - - print(gerar_serial(hardware_id, cliente, expiracao)) - - -if __name__ == "__main__": - main() +import argparse +import json +import os +from datetime import datetime + +from cryptography.fernet import Fernet + + +LEGACY_LICENSE_KEY = b"vS-C5Z_R1ST-Gf_K8_L9_Xo2-M1A3B5C7D9E1F2G3H4=" + + +def load_master_key() -> bytes: + env_key = os.getenv("VFM_LICENSE_MASTER_KEY") + if env_key: + return env_key.encode("utf-8") + return LEGACY_LICENSE_KEY + + +def parse_args(): + parser = argparse.ArgumentParser(description="Gerador de licenca do V-Fire Monitor") + parser.add_argument("--hwid", help="Hardware ID do cliente") + parser.add_argument("--cliente", help="Nome do cliente") + parser.add_argument("--expira", help="Data de expiracao no formato AAAA-MM-DD") + return parser.parse_args() + + +def ask_if_missing(value: str, prompt: str) -> str: + return value if value else input(prompt).strip() + + +def validate_expiration(date_text: str) -> str: + datetime.strptime(date_text, "%Y-%m-%d") + return date_text + + +def gerar_serial(hardware_id: str, cliente: str, data_expiracao: str) -> str: + fernet = Fernet(load_master_key()) + payload = {"h": hardware_id.strip(), "c": cliente.strip(), "e": validate_expiration(data_expiracao)} + return fernet.encrypt(json.dumps(payload, ensure_ascii=False).encode("utf-8")).decode("utf-8") + + +def main(): + args = parse_args() + + hardware_id = ask_if_missing(args.hwid, "Hardware ID do cliente: ") + cliente = ask_if_missing(args.cliente, "Nome do cliente: ") + expiracao = ask_if_missing(args.expira, "Validade (AAAA-MM-DD): ") + + if not hardware_id: + raise SystemExit("Hardware ID obrigatorio.") + if not cliente: + raise SystemExit("Nome do cliente obrigatorio.") + + print(gerar_serial(hardware_id, cliente, expiracao)) + + +if __name__ == "__main__": + main() diff --git a/installer/install_debian13.sh b/installer/install_debian13.sh new file mode 100644 index 0000000..563d038 --- /dev/null +++ b/installer/install_debian13.sh @@ -0,0 +1,640 @@ +#!/usr/bin/env bash +set -Eeuo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +CONFIG_FILE="${1:-${SCRIPT_DIR}/vfire-stack.env}" +DRY_RUN=0 + +APP_USER="vfire-monitor" +APP_GROUP="vfire-monitor" +APP_HOME="/opt/vfire-monitor" +APP_VENV="${APP_HOME}/.venv" +APP_STATE_DIR="/var/lib/vfire-monitor" +APP_LOG_DIR="/var/log/vfire-monitor" +APP_SERVICE="vfire-monitor.service" +APP_ENV_FILE="/etc/default/vfire-monitor" +APP_SYSTEMD_FILE="/etc/systemd/system/${APP_SERVICE}" + +ZABBIX_APT_KEYRING="/usr/share/keyrings/zabbix.gpg" +ZABBIX_APT_LIST="/etc/apt/sources.list.d/zabbix.list" +GRAFANA_APT_KEYRING="/etc/apt/keyrings/grafana.asc" +GRAFANA_APT_LIST="/etc/apt/sources.list.d/grafana.list" +GRAFANA_DASHBOARD_DIR="/var/lib/grafana/dashboards/vfire" +SUMMARY_FILE="/root/vfire-stack-summary.txt" + +log() { + printf '[vfire-installer] %s\n' "$*" +} + +die() { + printf '[vfire-installer] ERROR: %s\n' "$*" >&2 + exit 1 +} + +run_cmd() { + if [[ "${DRY_RUN}" == "1" ]]; then + printf '[dry-run] %s\n' "$*" + return 0 + fi + "$@" +} + +parse_args() { + local positional=() + while (($#)); do + case "$1" in + --dry-run) + DRY_RUN=1 + shift + ;; + *) + positional+=("$1") + shift + ;; + esac + done + + if ((${#positional[@]} > 0)); then + CONFIG_FILE="${positional[0]}" + fi +} + +require_root() { + [[ "${EUID}" -eq 0 ]] || die "Execute como root." +} + +require_supported_os() { + source /etc/os-release + [[ "${ID}" == "debian" ]] || die "Este instalador suporta apenas Debian." + [[ "${VERSION_CODENAME:-}" == "trixie" ]] || die "Este instalador foi preparado para Debian 13 (trixie)." +} + +random_secret() { + tr -dc 'A-Za-z0-9' /dev/null 2>&1 || die "Comando obrigatorio ausente: ${cmd}" + done +} + +assert_ports_available() { + local port + [[ "${DRY_RUN}" == "1" ]] && return 0 + for port in "${VFM_APP_PORT}" "${ZABBIX_WEB_PORT}" "${GRAFANA_PORT}"; do + if ss -ltn "( sport = :${port} )" | tail -n +2 | grep -q .; then + die "Porta ${port} ja esta em uso." + fi + done +} + +apt_install() { + if [[ "${DRY_RUN}" == "1" ]]; then + printf '[dry-run] DEBIAN_FRONTEND=noninteractive apt-get install -y %s\n' "$*" + return 0 + fi + DEBIAN_FRONTEND=noninteractive apt-get install -y "$@" +} + +write_zabbix_repo() { + run_cmd install -d -m 0755 /usr/share/keyrings + if [[ "${DRY_RUN}" == "1" ]]; then + printf '[dry-run] curl -fsSL https://repo.zabbix.com/zabbix-official-repo.key | gpg --dearmor -o %s\n' "${ZABBIX_APT_KEYRING}" + else + curl -fsSL "https://repo.zabbix.com/zabbix-official-repo.key" | gpg --dearmor -o "${ZABBIX_APT_KEYRING}" + fi + run_cmd chmod 0644 "${ZABBIX_APT_KEYRING}" + cat >"${ZABBIX_APT_LIST}" <Ative a licenca deste equipamento para liberar o monitoramento.
-Hardware ID
-{{ hwid }}
-
-
- Ative a licenca deste equipamento para liberar o monitoramento.
+Hardware ID
+{{ hwid }}
+
+
+