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
π Full Documentation | π Deployment Guide | π» Architecture | π Security | π£οΈ Roadmap
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)
# 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.
# 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.
- β 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)
- β 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
- β 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
- β 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 profile management and password change
- β Admin user creation and role assignment
- β Group-based permissions
- β Account lockout and unlock
- β 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.)
| 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 |
- π 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
- ποΈ 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
- π Changelog - Detailed history of all releases
- π’ Release Notes - Highlights of latest release
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.
Deliver custom analytics portals to clients with role-based access, audit trails, and automatic HTTPS. One instance per client for complete data isolation.
Host internal analytics portals with organizational hierarchies, group-based permissions, and comprehensive audit logging for compliance.
Create reusable analytics hosting infrastructure as a platform component, with templated deployments and standardized security practices.
- 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
- .NET 10 SDK
- Node.js 18+ with npm
- Git
- VS Code (optional)
- Docker and Docker Compose installed
- A domain name pointing to your server (for HTTPS)
- Ports 80 and 443 open on your firewall
-
Clone the repository
git clone <repository-url> cd PBIHoster/deployment
-
Configure environment
cp .env.example .env
-
Generate a secure JWT key
openssl rand -base64 32
Copy the output for the next step.
-
Edit
.envfilenano .env
Critical settings to change:
JWT_KEY: Paste the key generated in step 3CORS_ORIGIN_1: Your domain (e.g.,https://reports.company.com)
-
Update Caddyfile with your domain
nano Caddyfile
Replace
your-domain.comwith your actual domain. -
Deploy using Docker Compose
docker-compose up -d
This will pull and run the official image
ghcr.io/aenas11/pbihoster:mainas defined indocker-compose.yml. The backend, frontend, and database are all included in this image. Caddy will handle HTTPS and reverse proxy. -
Verify deployment
# Check containers are running docker-compose ps # View logs docker-compose logs -f pbihoster
-
Access the application
- Navigate to
https://your-domain.com - Register the first user account
- Promote first user to Admin (see First Time Setup)
- Navigate to
For local development without Docker.
- .NET 10 SDK
- Node.js 18+ and npm
- Git
-
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
-
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)
-
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
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
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.
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
See Contributing Guide for development environment setup with hot-reload.
- β 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)
See Security Guide for detailed security implementation and:
- Change
JWT_KEYto a strong random value - Configure
CORS_ORIGINfor 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
PBIHoster follows a layered architecture:
Frontend (Vue 3 + TypeScript)
β
API Layer (ASP.NET Core REST API)
β
Service Layer (Business logic)
β
Repository Layer (Data access with LiteDB)
β
LiteDB (Embedded database)
See ARCHITECTURE.md for complete system design, data models, and integration patterns.
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.
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 |
See DATABASE.md for complete schema documentation and query examples.
- π 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
We welcome contributions! See CONTRIBUTING.md for:
- Development setup guide
- Code standards and conventions
- Pull request process
- Testing requirements
When reporting bugs, please include:
- Your environment (Docker, local, Kubernetes, etc.)
- Application version (from
/versionendpoint) - Steps to reproduce
- Expected vs. actual behavior
- Relevant logs (from
/api/auditor container logs)
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
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
- 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
- GitHub: aenas11/pbihoster
- Issues: Report a bug
- Discussions: Ask a question
Last Updated: 2025-02-06 | Version: 0.3.0
Symptom: Legitimate users getting "Too Many Requests" errors
Solution:
- Increase rate limits in
.env:RATE_LIMIT_GENERAL=200 RATE_LIMIT_GENERAL_PERIOD=1m
- Restart:
docker-compose restart pbihoster
Symptom: Users can't authenticate despite correct credentials
Solution:
- Verify
JWT_KEYhasn't changed (changing it invalidates all tokens) - Check
JWT_EXPIRY_HOURSisn't too short - Verify server system clock is accurate
Symptom: Application can't start or errors mention LiteDB
Solution:
- Check database file permissions:
/data/reporttree.dbmust be writable - Verify volume mount in
docker-compose.yml - Check disk space:
df -h
Symptom: Blank page or 404 errors
Solution:
- Verify backend built the frontend: Check
ReportTree.Server/wwwroot/has files - Rebuild:
dotnet publish ReportTree.Server/ReportTree.Server.csproj - Check Caddy logs:
docker-compose logs caddy
Check logs:
# Application logs
docker-compose logs -f pbihoster
# Caddy (web server) logs
docker-compose logs -f caddy
# All logs
docker-compose logs -fVerify containers:
docker-compose psRestart services:
# Restart everything
docker-compose restart
# Restart specific service
docker-compose restart pbihoster- Database: LiteDB file at
/data/reporttree.db(embedded, no separate server) - Collections: Users, Pages, Groups, Themes, AuditLogs, Settings, LoginAttempts
- Backups: Simply backup the
/datadirectory
- 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
/- Home/Welcome page/login- Login page/profile- User profile/admin- Admin panel (Admin only)/page/:id- Dynamic page viewer
[Your License Here]
[Your Contribution Guidelines Here]
For issues and questions:
- Check the Troubleshooting section
- Review logs with
docker-compose logs - Open an issue on GitHub