PBIHoster

A modern, secure Power BI hosting platform for embedding analytics into applications and portals. Built for ISVs, consultancies, and enterprises that need to manage Power BI reports with user authentication, role-based access control, and corporate branding.

Current Version: v0.4.0 | License: MIT | Status: Actively Maintained

Quick Links

📖 Full Documentation | 🚀 Deployment Guide | 💻 Architecture | 🔒 Security | 🛣️ Roadmap

---

What is PBIHoster?

PBIHoster is an open-source platform for hosting and managing Power BI reports using the "App owns the data" embedding model. It provides:

• Secure Multi-User Access: JWT-based authentication with role-based access control
• Dynamic Content Organization: Hierarchical page tree with drag-and-drop dashboard layouts
• Enterprise Branding: Custom themes, logos, and white-labeling capabilities
• Comprehensive Audit Trail: Track all user actions and security events
• Simple Deployment: Docker Compose with automatic HTTPS via Caddy
• Zero Operational Dependencies: Embedded LiteDB database (no external servers)

Table of Contents

• Quick Start
• Key Features
• Tech Stack
• Documentation
• Use Cases
• Getting Help

Quick Start

Docker (Recommended for Production)

# 1. Clone repository
git clone https://github.com/aenas11/pbihoster.git
cd pbihoster/deployment

# 2. Setup configuration
cp .env.example .env
openssl rand -base64 32 > jwt_key.txt
# Edit .env and set JWT_KEY, CORS_ORIGIN_1, and Power BI credentials

# 3. Update domain in Caddyfile
nano Caddyfile  # Replace yourdomain.com with your domain

# 4. Deploy
docker-compose up -d

# 5. Access application
# Navigate to https://yourdomain.com and register the first user (auto-promoted to Admin)

See DEPLOYMENT.md for detailed production setup and Power BI configuration.

Local Development

# Backend (requires .NET 10 SDK)
cd ReportTree.Server
dotnet watch run          # http://localhost:5001

# Frontend (requires Node.js 18+, in another terminal)
cd reporttree.client
npm install && npm run dev  # http://localhost:5173

# Access http://localhost:5173 (API requests proxy to backend)

See CONTRIBUTING.md for full development setup.

---

Key Features

🔐 Security & Authentication

• ✅ JWT-based authentication with account lockout protection
• ✅ Three user roles: Admin (full control), Editor (create/edit), Viewer (read-only)
• ✅ Password complexity enforcement
• ✅ API rate limiting (prevents brute force and DoS)
• ✅ Comprehensive audit logging (all user actions)
• ✅ CORS protection and security headers
• ✅ External identity provider login (OIDC/OAuth2) with local JWT issuance
• ✅ External claim-to-role and claim-to-group mapping controls for admins (non-secret settings only)

📊 Content Management

• ✅ Hierarchical page tree (unlimited nesting for organizing reports)
• ✅ Drag-and-drop layout system with components
• ✅ Role-based and group-based access control per page
• ✅ Public page support (no authentication required)
• ✅ Favorites and bookmarks
• ✅ Edit mode for managing structure without navigating

🎨 Customization & Branding

• ✅ Four built-in themes (White, Gray 10, Gray 90, Gray 100) from Carbon Design System
• ✅ Custom corporate themes with full color control
• ✅ Logo upload and favicon customization
• ✅ Custom footer links
• ✅ App name customization

📈 Power BI Integration

• ✅ Secure embedding with "App owns the data" model
• ✅ Row-Level Security (RLS) support with component-level configuration
• ✅ Dynamic workspace selection
• ✅ Report and dashboard embedding
• ✅ Dataset Refresh Management (Admin)
  • ✅ Scheduled refresh with cron expressions and time zone support
  • ✅ Manual refresh triggering with rate limiting
  • ✅ Refresh history and status tracking
  • ✅ Email and webhook notifications
  • ✅ Retry policy with exponential backoff
  • ✅ CSV export of refresh history

👥 User & Group Management

• ✅ User profile management and password change
• ✅ Admin user creation and role assignment
• ✅ Group-based permissions
• ✅ Account lockout and unlock

📋 Audit & Compliance

• ✅ Comprehensive audit logging
• ✅ Filtering by user, resource, action, date range, and success state
• ✅ Export audit logs as CSV and PDF
• ✅ Security event tracking (failed logins, lockouts, etc.)

---

Tech Stack

Layer	Technology	Notes
Backend	ASP.NET Core (.NET 10)	Modern, high-performance web API
Frontend	Vue 3 + TypeScript + Vite	Reactive SPA with type safety
Database	LiteDB	Embedded NoSQL - no separate DB server
UI Components	Carbon Design System v11	Enterprise-grade design system
Authentication	JWT Bearer Tokens	Stateless, scalable auth
Deployment	Docker + Docker Compose	Single container with all components
Reverse Proxy	Caddy	Automatic HTTPS with Let's Encrypt

---

Documentation

User & Deployment

• 🚀 Deployment Guide - Production setup, Power BI configuration, security checklist
• 📧 Email Setup Guide - Configure SMTP for refresh notifications (Gmail, Office 365, SendGrid, etc.)
• 📖 User Guide - Creating pages, managing users, configuring themes
• 🔒 Security Guide - Authentication, authorization, best practices
• 📋 Operations & Troubleshooting - Monitoring, common issues, recovery

Developers

• 🏗️ Architecture - System design, layered architecture, data models
• 🔌 API Documentation - REST endpoints, authentication, error handling
• 🗄️ Database Schema - LiteDB collections, relationships, queries
• 🤝 Contributing - Development setup, code standards, PR process
• 🛣️ Roadmap - Planned features, implementation timeline

Reference

• 📝 Changelog - Detailed history of all releases
• 📢 Release Notes - Highlights of latest release

---

Use Cases

ISVs & SaaS Products

Embed Power BI analytics directly into your application, whitelabeled with your branding. Users don't need Power BI licenses—your app manages authentication and access.

Management Consultancies

Deliver custom analytics portals to clients with role-based access, audit trails, and automatic HTTPS. One instance per client for complete data isolation.

Enterprise Analytics Teams

Host internal analytics portals with organizational hierarchies, group-based permissions, and comprehensive audit logging for compliance.

Solution Architects

Create reusable analytics hosting infrastructure as a platform component, with templated deployments and standardized security practices.

---

Installation Requirements

For Docker Deployment (Production)

• Docker & Docker Compose
• A domain name with DNS pointing to your server
• Ports 80 and 443 open (HTTP/HTTPS)
• Azure AD app for Power BI integration

For Local Development

• .NET 10 SDK
• Node.js 18+ with npm
• Git
• VS Code (optional)

---

User Guide

First Time Setup

1. Access the application

   • Navigate to your deployment URL
   • Click "Register" and create your first user account
   • The first user is automatically promoted to Admin role
   • Log in with your credentials

2. Configure basic settings (as Admin)

   • Navigate to Admin Panel → Settings
   • Set your organization's name, logo, and colors
   • Configure Power BI integration (if using reports)

3. Create your first page (optional)

   • Click "Edit Pages" in the sidebar
   • Add a new top-level page
   • Assign roles that can access it
   • Save and exit edit mode

Managing Content

Creating Pages & Hierarchy

• Pages can be nested infinitely (folders → subfolders → pages)
• Each page can have a layout with draggable components
• Set access control per page (roles, users, groups, or public)
• See ARCHITECTURE.md for data model details

Embedding Power BI Reports

• Add "Power BI Report" components to page layouts
• Select workspace, report, and optionally configure RLS roles
• Reports display securely within your app

Managing Users

• Create users in Admin Panel → Users
• Assign roles (Admin, Editor, Viewer)
• Add users to groups for bulk access management
• Reset passwords or unlock accounts as needed

Demo Mode & Sample Content

Toggle Demo Mode in Admin Panel → Settings to see:

• Sample pages and navigation structure
• Sample Power BI report preview (static)
• Sample dataset for reference

Useful for exploring without configuring Power BI first.

---

Deployment

Deployment Options

graph LR
    subgraph Docker["🐳 Docker Compose (Recommended)"]
        D1["Single container\n(backend + frontend + LiteDB)"]
        D2["Caddy sidecar\n(HTTPS + reverse proxy)"]
        D1 --- D2
    end

    subgraph Local["💻 Local Development"]
        L1["dotnet watch run\n:5001"]
        L2["npm run dev\n:5173 (proxies /api → backend)"]
    end

    subgraph K8s["☸️ Kubernetes"]
        K1["Single replica pod\n(LiteDB — RWO PVC)"]
        K2["OR multi-replica\n(requires relational DB migration)"]
    end

Loading

Production Deployment (Recommended)

See the comprehensive Deployment Guide for:

• Step-by-step Docker Compose setup
• Power BI configuration and authentication
• Security hardening checklist
• HTTPS and reverse proxy setup
• Backup and recovery procedures

Local Development

See Contributing Guide for development environment setup with hot-reload.

---

Security & Compliance

Security Features

• ✅ JWT-based authentication with automatic expiry
• ✅ Password complexity enforcement and account lockout
• ✅ Row-Level Security (RLS) for Power BI reports
• ✅ Role-based access control (Admin, Editor, Viewer)
• ✅ Group-based permissions for bulk access management
• ✅ API rate limiting (prevents brute force attacks)
• ✅ Comprehensive audit logging (all actions tracked)
• ✅ Security headers and CORS protection
• ✅ Encrypted credentials and sensitive data at rest
• ✅ Automatic HTTPS with Let's Encrypt (Docker)

Pre-Production Checklist

See Security Guide for detailed security implementation and:

• Change JWT_KEY to a strong random value
• Configure CORS_ORIGIN for your domain(s)
• Set up database backups
• Review and adjust password policy
• Enable audit log monitoring
• Test account lockout recovery
• Verify Power BI service principal configuration

---

Architecture & Technical Details

System Architecture

PBIHoster follows a layered architecture:

graph TD
    FE["Vue 3 + TypeScript\nPinia · Vue Router · Carbon Design System"]
    API["ASP.NET Core REST API\nControllers · Minimal APIs · Middleware"]
    SVC["Service Layer\nAuthService · PowerBIService · AuditLogService · ..."]
    REPO["Repository Layer\nIUserRepository · IPageRepository · ..."]
    DB[("Pluggable Database\nLiteDB (default) · Sqlite · SQL Server · PostgreSQL")]
    EXT["External Services\nAzure AD · Power BI API · Email · Key Vault"]

    FE -->|HTTP /api/*| API
    API --> SVC
    SVC --> REPO
    REPO --> DB
    SVC --> EXT

Loading

See ARCHITECTURE.md for complete system design, data models, and integration patterns.

REST API

All operations are available via REST API:

curl -X GET https://your-domain.com/api/pages \
  -H "Authorization: Bearer $TOKEN"

See API.md for complete endpoint documentation with examples.

Database Schema

LiteDB collections and their relationships:

Collection	Purpose
AppUser	User accounts, authentication
Page	Page hierarchy, layouts, access control
AppSetting	Configuration (encrypted for sensitive data)
AuditLog	Comprehensive audit trail
Group	User groups for bulk access management
CustomTheme	Custom branding and color tokens
LoginAttempt	Failed login tracking (lockout)
DatasetRefreshSchedule	Scheduled Power BI dataset refreshes
DatasetRefreshRun	Refresh execution history
Comment	Threaded page comments and @mentions
PageVersion	Page layout version history and rollback snapshots

See DATABASE.md for complete schema documentation and query examples.

---

Support & Community

Getting Help

• 📖 Full Documentation - Guides for all topics
• 🐛 GitHub Issues - Bug reports and feature requests
• 💬 GitHub Discussions - Ask questions, share ideas
• 🛠️ TROUBLESHOOTING.md - Common issues and resolutions
• 🔑 Admin Password Recovery - CLI steps when admin credentials are lost

Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Development setup guide
• Code standards and conventions
• Pull request process
• Testing requirements

Reporting Issues

When reporting bugs, please include:

• Your environment (Docker, local, Kubernetes, etc.)
• Application version (from /version endpoint)
• Steps to reproduce
• Expected vs. actual behavior
• Relevant logs (from /api/audit or container logs)

---

Versioning & Releases

Semantic Versioning: Major.Minor.Patch (e.g., 0.3.0)

• CHANGELOG.md: Detailed history of all releases
• documentation/RELEASE_NOTES.md: Highlights of latest release
• ROADMAP.md: Planned features and timeline

---

License

PBIHoster is released under the MIT License - see LICENSE file for details.

You are free to:

• ✅ Use commercially
• ✅ Modify the source code
• ✅ Distribute and sublicense
• ✅ Use privately

---

Acknowledgments

• Microsoft Power BI for the embedded analytics platform
• Carbon Design System for the enterprise UI framework
• LiteDB for the embedded database
• Caddy for the automated reverse proxy

---

Related Resources

Microsoft Power BI

• Power BI Embedded Documentation
• Power BI REST API Reference
• App owns the data sample

Design System

• Carbon Design System
• Carbon Vue Components
• Carbon Icons

Technologies

• ASP.NET Core Documentation
• Vue 3 Guide
• LiteDB Documentation
• Docker Documentation

---

Contact & Links

• GitHub: aenas11/pbihoster
• Issues: Report a bug
• Discussions: Ask a question

---

Last Updated: 2025-02-06 | Version: 0.3.0

Rate Limiting (429 Errors)

Symptom: Legitimate users getting "Too Many Requests" errors

Solution:

1. Increase rate limits in .env:

   RATE_LIMIT_GENERAL=200
   RATE_LIMIT_GENERAL_PERIOD=1m

2. Restart: docker-compose restart pbihoster

JWT Token Validation Fails

Symptom: Users can't authenticate despite correct credentials

Solution:

1. Verify JWT_KEY hasn't changed (changing it invalidates all tokens)
2. Check JWT_EXPIRY_HOURS isn't too short
3. Verify server system clock is accurate

Database Issues

Symptom: Application can't start or errors mention LiteDB

Solution:

1. Check database file permissions: /data/reporttree.db must be writable
2. Verify volume mount in docker-compose.yml
3. Check disk space: df -h

Frontend Not Loading

Symptom: Blank page or 404 errors

Solution:

1. Verify backend built the frontend: Check ReportTree.Server/wwwroot/ has files
2. Rebuild: dotnet publish ReportTree.Server/ReportTree.Server.csproj
3. Check Caddy logs: docker-compose logs caddy

Getting Help

Check logs:

# Application logs
docker-compose logs -f pbihoster

# Caddy (web server) logs
docker-compose logs -f caddy

# All logs
docker-compose logs -f

Verify containers:

docker-compose ps

Restart services:

# Restart everything
docker-compose restart

# Restart specific service
docker-compose restart pbihoster

---

Architecture Notes

Data Storage

• Database: LiteDB file at /data/reporttree.db (embedded, no separate server)
• Collections: Users, Pages, Groups, Themes, AuditLogs, Settings, LoginAttempts
• Backups: Simply backup the /data directory

API Structure

• Base URL: /api/
• Auth Endpoints: /api/login, /api/register
• Protected Routes: Require Authorization: Bearer <token> header
• Admin Routes: Require Admin role
• Editor Routes: Require Admin or Editor role

Frontend Routes

• / - Home/Welcome page
• /login - Login page
• /profile - User profile
• /admin - Admin panel (Admin only)
• /page/:id - Dynamic page viewer

---

License

[Your License Here]

Contributing

[Your Contribution Guidelines Here]

Support

For issues and questions:

• Check the Troubleshooting section
• Review logs with docker-compose logs
• Open an issue on GitHub