DashLab+

Visão geral

O DashLab+ centraliza atalhos, métricas e disponibilidade dos serviços da sua rede. Uma única imagem contém a landing, o Lab e a API Go.

A API serve os arquivos web, persiste o estado no SQLite e integra Prometheus, clima e serviços internos. Todo o estado persistente fica no volume Docker dashlab_plus_data.

01

Requisitos

• Docker Engine 24 ou mais recente.
• Docker Compose v2.
• Um host Linux com acesso aos serviços monitorados.
• Prometheus é opcional, mas necessário para widgets de CPU, memória, discos e rede.

O navegador não precisa de Node.js no host de produção. As imagens oficiais suportam amd64 e arm64.

02

Instalação

O comando abaixo automatiza o Docker Compose: baixa a configuração, busca a imagem oficial e inicia o container.

1. Execute

curl -fsSL https://dashlabplus.vercel.app/install.sh | sh

O instalador verifica Docker e Compose, cria ~/.dashlab-plus, configura um atualizador interno e preserva sua configuração entre atualizações.

2. Configure, se necessário

As configurações são persistidas no banco. Para conectar o Prometheus e ajustar os filtros, abra Personalizar no Lab.

3. Confirme a saúde

curl http://IP-DO-HOST:3000/api/health

A resposta deve indicar status ok e armazenamento SQLite.

03

Configuração

A instalação normal não exige arquivo .env nem variáveis de ambiente. Usuários, preferências, integrações e dados do dashboard são salvos no banco SQLite do volume dashlab_plus_data.

DATABASE_PATH, WEB_ROOT e PORT são opções técnicas com valores padrão na imagem e não precisam ser configuradas no uso normal.

04

Prometheus

Configure a URL e os filtros em Lab → Personalizar → Integrações. A URL precisa ser resolvida de dentro do container dashlab-plus. Use um IP da LAN ou um nome DNS disponível na mesma rede Docker.

Sem PROMETHEUS_URL, o dashboard continua funcionando, mas os widgets de sistema, armazenamento e rede ficam indisponíveis.

05

Primeiro uso

1. No primeiro acesso, crie o usuário administrador. Nos acessos seguintes, entre com seu usuário e senha; administradores podem criar usuários comuns pelo botão de usuários no Lab. Use o botão Sair na barra de ações para encerrar sua sessão neste dispositivo.
2. Abra Personalizar para definir nome, cores, logo, favicon, wallpaper, escala e comportamento mobile.
3. Use Adicionar para cadastrar aplicativos, widgets ou seções.
4. Em aplicativos, informe o endereço principal e, opcionalmente, uma URL de status e um deep link mobile.
5. Crie widgets de sistema, armazenamento, rede, relógio, status, PromQL ou divisória.
6. No desktop, ative Editar organização, selecione um item e arraste ou redimensione pelas alças.
7. No celular, escolha Grade, Menu lateral ou Barra inferior em Personalizar.
8. Instale o PWA pelo menu do navegador para abrir o dashboard como aplicativo.

As alterações são salvas imediatamente no SQLite e ficam disponíveis em todos os seus dispositivos.

06

Como funciona o Lab

O Lab é o dashboard operacional do DashLab+. O primeiro usuário é administrador e pode criar usuários comuns, que acessam e editam o dashboard sem gerenciar contas ou atualizações.

Aplicações e seções

Cadastre cada serviço com nome, URL, descrição, ícone, URL de status e deep link mobile. Aplicações podem ser agrupadas em seções recolhíveis; o indicador de disponibilidade consulta a URL de status (ou a URL principal quando ela não existe).

Widgets e métricas

Widgets de sistema, armazenamento e rede usam métricas do Prometheus. Status resume as verificações das aplicações, PromQL executa uma consulta configurada por você e relógio mostra a hora local. O clima exibido no cabeçalho usa localização configurada ou geolocalização do navegador; não é um widget editável.

Organização e personalização

No desktop, ative Editar organização para selecionar, arrastar e redimensionar elementos. No celular, o Lab aplica o modo Grade, Menu lateral ou Barra inferior escolhido em Personalizar. Nome, cores, logo, favicon, wallpaper, escala e opacidade são salvos no dashboard.

API do Lab

O frontend React conversa somente com a API Go local. A API valida e persiste alterações, consulta integrações e serve os arquivos estáticos. Os principais recursos são:

• GET /api/dashboard — estado do dashboard e layouts.
• PUT /api/branding — preferências visuais.
• POST/PATCH/DELETE /api/applications — atalhos e serviços.
• POST/PATCH/DELETE /api/widgets — widgets e configurações.
• GET /api/metrics/* — métricas do Prometheus.
• GET /api/applications/status — disponibilidade dos serviços.
• GET/POST /api/auth/* — primeiro acesso, login, logout e gerenciamento de usuários.
• POST /api/update — atualiza frontend e backend pelo updater interno (administrador).

07

Arquitetura

Navegador
   │
   ▼
DashLab+ :3000
   ├── Landing + Lab
   ├── API /api
   ├── SQLite /data/dashlab-plus.db
   ├── Prometheus
   ├── Open-Meteo
   └── serviços da LAN

Um único processo Go serve os arquivos React/Vite e a API consumida pelo dashboard. Ele guarda configuração e imagens no SQLite.

Por que uma API ainda existe?

O navegador não deve acessar diretamente o Prometheus e não consegue verificar todos os serviços internos por causa de CORS. A API também mantém o mesmo estado entre desktop e celular.

08

Persistência e backup

O volume dashlab_plus_data contém o banco e os arquivos auxiliares de WAL. Pare o container antes de copiar o volume:

docker stop dashlab-plus
docker run --rm -v dashlab_plus_data:/source -v "$PWD":/backup alpine \
  tar -czf /backup/dashlab-plus-data.tar.gz -C /source .
docker start dashlab-plus

Para restaurar, crie uma instalação limpa, pare o container e extraia o backup no mesmo volume. Mantenha uma cópia fora do host.

09

Atualização

curl -fsSL https://dashlabplus.vercel.app/install.sh | sh

O instalador configura o updater interno. O volume SQLite permanece intacto durante as atualizações.

Quando uma versão publicada for detectada, o DashLab+ mostra um aviso com as cores do tema atual. Clique em Atualizar para baixar a imagem nova e recriar o container; frontend e backend são atualizados juntos e sua sessão continua ativa.

O aviso de atualização aparece somente no Lab instalado no servidor. A landing page pública e a documentação não exibem esse aviso. A atualização mantém o volume dashlab_plus_data.

10

Segurança

• Prefira Tailscale, WireGuard ou outra VPN para acesso remoto.
• Se usar proxy reverso público, exija autenticação em todas as rotas, inclusive /api.
• Configure os destinos do Prometheus e dos checks de status em Personalizar → Integrações.
• Não publique Prometheus ou SQLite.
• Mantenha as imagens Docker e o host atualizados.
• O atualizador interno usa o socket do Docker; mantenha a porta 3000 restrita à LAN/VPN ou ao proxy reverso.
• Use HTTPS quando houver tráfego fora da LAN.

11

Solução de problemas

Widgets exibem zero ou indisponível

Confira a URL e os filtros em Personalizar → Integrações e a conectividade a partir do container.

Um serviço aparece offline

A URL de status precisa ser acessível pela rede do container. Prefira um endpoint de saúde sem login interativo.

Alterações não permanecem

Verifique o volume e execute docker logs dashlab-plus. O container precisa escrever em /data.

PWA mantém conteúdo antigo

Recarregue ignorando o cache ou remova e instale novamente o PWA.

Suporte

Abra uma issue no GitHub com versão, logs relevantes e passos para reproduzir, removendo informações sensíveis.