raulcnadal/applivery-big-picture repository overview

Applivery Big Picture is a unified, real-time analytics and reporting dashboard for your Applivery workspaces. It provides a visual overview of your device fleet, app distribution, compliance status, users, and geographic locations through an interactive 3D globe and an automated PDF reporting engine—all packaged in a single, lightweight Docker container.

⁠ Key Features

• Real-time Analytics: Track device OS distributions, compliance status, app downloads, synchronization errors, and available OS updates.
• Interactive 3D Globe: Visualize your device fleet geographically with live status indicators, orbiting satellites, and atmospheric effects.
• Automated PDF Reporting: Build, schedule, and automate high-fidelity PDF reports with native delivery via Google Chat Webhooks or SMTP Email.
• Customizable Grid: Drag, drop, and resize widgets to build your perfect dashboard layout.
• Enterprise Security: Protected by a unified JWT backend, automatic session timeouts, and built-in support for OIDC Single Sign-On (SSO).
• Global State Persistence: Dashboard layouts, schedules, and configurations are synchronized globally across all your devices via the backend container volume.

⁠ Core Capabilities & Deep Dives

Applivery Big Picture goes beyond top-level metrics, allowing administrators to drill down into the exact state of their device fleet, segment hierarchy, and app ecosystem.

⁠🎨 Customizable Dashboard & Widgets

Design your perfect view by adding, dragging, resizing, and locking widgets to the responsive grid.

• 9 Chart Types: Choose between Scorecards, Gauges, Donuts, Solid Pies, Bar charts, Line trends, Radar charts, Lists, and Progress bars.
• Extensive Data Catalog: Over 20 distinct data sources categorized by UEM Devices, Users & Segments, App Distribution, and System Health.
• Granular Filtering: Filter widgets globally or individually by Organizational Segments, Operating System, Compliance Status, User Roles, Authentication Origins, or choose to hide devices inactive for 24 hours.

⁠🌍 Interactive 3D Globe Playground

Switch to the Playground view to see your entire fleet mapped in real-time across a 3D Earth, complete with a static starry night sky, atmospheric clouds, and active scanning satellites.

• Smart Positioning: Uses exact GPS cache data, last reported MDM location, or Network IP fallbacks to plot devices.
• Visual Compliance: Devices pulse dynamically on the map—green for compliant, red for non-compliant. Communication arcs visualize active data links.
• Quick Filters: Instantly toggle the map to show only "Non-Compliant" devices to quickly identify geographic risk clusters.
• Sync Engine: Manually trigger a background sync to fetch the latest latitude/longitude coordinates directly from the Applivery API.

⁠📈 Automated Reporting Engine

A fully-featured reporting suite allows administrators to extract and deliver data without lifting a finger.

• Report Builder: Select data sources, apply custom filters, define time lapses, and customize the visual output (Trend lines vs. bars, Pie vs. Radar, Standard tables vs. Progress bars).
• Delivery Methods: Download PDFs directly, or route them to Google Chat via Webhooks and directly to stakeholders via the built-in SMTP Email engine.
• Background Scheduler: Enable automation to run reports on a recurring schedule (Daily, Weekly, or Monthly) at a specific time, synchronized flawlessly to your local timezone.

⁠🔍 Deep-Dive Insight Cards

Every chart, graph, and globe marker is fully interactive. Clicking a slice of a donut chart or a specific OS trend instantly opens a filtered list. Clicking any specific asset opens a rich Insight Card with extensive telemetry:

• Workspace Profile: View your organization's exact usage versus limits with real-time progress bars for Apps, Installations, Collaborators, Employees, Devices, and Asset Storage (GB). Track ecosystem policies, active privileges, and contact details.
• Device Telemetry: * Overview: View battery health, storage capacity, OS version, Manufacturer, Model, Serial Number, IMEI, MAC Address, UDID, and IP Address. Track enrollment dates and active policies.
  • Location: View an embedded OpenStreetMap of the device's exact current location alongside Google Maps deep links and a full chronological location history.
  • Assets & Agent: See exactly which enterprise applications are assigned to the device's segment and scroll through real-time MDM agent telemetry logs right from the browser.
• App Distribution: Track specific enterprise apps to see total builds, downloads, feedback counts, and a timeline of the most recent processed builds by OS.
• User & Segment Hierarchy: View users' assigned roles, segment permissions, managed device counts, and activity trace (last store/dashboard login). Browse your entire organizational structure via the interactive Segment Tree.

⁠ Quick Deployment

The application runs as a single unified container (React frontend + FastAPI backend). It strictly requires two environment variables to secure your administrative sessions.

⁠Environment Variables

• DASHBOARD_PASSWORD: The master password used to log in via the "Local Admin" prompt.
• DASHBOARD_SECRET: A secure, random string used to sign backend JWT sessions.

⁠Option A: Docker Run

docker run -d \
  -p 8000:8000 \
  -e DASHBOARD_PASSWORD="YourSecurePasswordHere" \
  -e DASHBOARD_SECRET="GenerateARandomSecretKeyHere" \
  -v $(pwd)/data:/app/data \
  --name applivery-big-picture \
  raulcnadal/applivery-big-picture:latest

⁠Option B: Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  applivery-big-picture:
    image: raulcnadal/applivery-big-picture:latest
    container_name: applivery-big-picture
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data
    environment:
      - DASHBOARD_PASSWORD=YourSecurePasswordHere
      - DASHBOARD_SECRET=GenerateARandomSecretKeyHere

Run the stack using:

docker compose up -d

⁠ Administrator Guide

Once your container is running, navigate to http://localhost:8000 in your web browser.

⁠1. First-Run Setup

On your first visit, the app will guide you through connecting to your Applivery Workspace:

1. Workspace Slug: The unique identifier for your Applivery organization (e.g., your-organization).
2. Service Token: Your Applivery API token (starts with sk_live_...).
3. Local Admin Validation: Enter the exact password you defined in the DASHBOARD_PASSWORD environment variable to authenticate the setup.

⁠2. Authentication & SSO

Big Picture supports two login methods:

• Local Admin: Uses the DASHBOARD_PASSWORD passed to the Docker container.
• OIDC SSO: Configure your identity provider (IdP) in the Setup Wizard or Settings panel. The callback URI for your IdP is:
  • http://<your-domain.com>/auth/callback
  • Required scopes: openid profile email

Note: For security, administrative sessions will automatically time out after 15 minutes of inactivity.

⁠3. Data Persistence & Backups

Unlike previous versions, Big Picture now features a Unified Backend State. Your dashboard layouts, SSO configuration, SMTP settings, and scheduled reports are saved globally to the /app/data/state_global.json file inside your Docker volume. Any authorized user logging in from any device will immediately see the configured layout.

• To backup your dashboard: Open the Settings menu and click Export JSON.
• To restore: Click Import JSON in the Settings menu to instantly restore a previously saved layout and configuration state.

⁠4. System Settings (SMTP & Webhooks)

To utilize the automated delivery features of the Reporting Engine, you must configure your endpoints:

• Navigate to Settings (gear icon in the top right).
• Fill out the SMTP Email Engine configuration (Host, Port, Username, Password, and Sender Address) to enable automated email PDFs. You can send a test email directly from this menu.
• Supply a Google Chat Webhook URL to enable automated chat alerts when reports finish generating.