From install to embedded analytics — a practical guide.
Yurbi is self-hosted and built for technical teams. This guide walks you through every phase of implementation — what to do, what to plan for, and where most teams spend their time. Not every click; the right mental model.
Eight phases. Each builds on the last.
Phases 1–3 are mostly technical setup — under a day for an experienced team. Phases 4–5 are where you spend real time, because they're specific to your data and your customers. Phases 6–8 are the payoff.
Prerequisites & Planning
A little planning before installation saves real time later. The two decisions that matter most: what server environment you're deploying to, and whether you're using PostgreSQL or MS SQL Server as Yurbi's backend database. Both work — MS SQL is recommended for high-volume multi-tenant deployments.
What to sort out before you install
-
Server sizing Minimum 8 GB RAM, x86/amd64 architecture. Windows Server 2016+ or Windows 10/11, Ubuntu/Debian/RHEL, or Docker Engine 20.10+. ARM is not supported.
-
Backend database choice Yurbi stores its own configuration in either PostgreSQL (embedded default, fine for most deployments) or MS SQL Server (recommended for enterprise scale and high-volume multi-tenant). Decide this before install.
-
Network access plan Yurbi needs to reach your application database. Decide whether it's on the same network, a separate host, or behind a firewall rule. Also plan the URL your users will access — a readable internal URL (not a server hostname) improves adoption.
-
Read-only database credentials Yurbi is read-only by design, but you should still create dedicated read-only credentials for it to connect to your application database. Never use an admin account.
-
Deployment model decision Are you running one Yurbi instance for all your customers (multi-tenant, most common for ISVs), or one instance per customer server? This affects how you configure Tenant Mode and App Shield in Phase 5.
Install & Activate
Installation is the fastest phase. Yurbi ships as a standard installer for Windows, a package for Linux, and a Docker image — pick your environment and you're running in minutes. After install, an activation wizard walks you through trial license setup on first login.
Windows
Run the installer, follow the wizard. IIS or Yurbi's built-in web server. Windows Server 2016+ or Windows 10/11 (x64).
Linux
Package install on Ubuntu, Debian, RHEL, or compatible. Systemd service included. 8 GB RAM minimum.
Docker
Docker Engine 20.10+, x86/amd64 only. ARM is not supported. Compose file provided.
dev_yourcompany@yurbi.com or prod_yourcompany@yurbi.com — it helps our team identify your server quickly if you need a trial extension or license assistance.Connect Your Data
Yurbi connects directly to your application database — the same one your product already uses. There's no ETL pipeline, no separate data warehouse required. You register the connection in Yurbi's admin panel, test it, and move on.
Native drivers (recommended)
For PostgreSQL, SQL Server, MySQL, MariaDB, and Oracle — use Yurbi's native drivers. Enter the host, port, database name, and your read-only credentials. Test the connection. Done. Cloud-managed variants (RDS, Aurora, Azure SQL, Cloud SQL) use the same native drivers.
ODBC (for everything else)
For Snowflake, Redshift, BigQuery, MongoDB Atlas, Trino, and others — install the appropriate ODBC driver on the Yurbi server, configure a DSN, and connect via the ODBC path. This requires server-level access and a bit more setup, but the pattern is consistent across drivers.
Build the Semantic Layer
This is the phase most teams underestimate — and the one that makes everything else work. The Yurbi App is the semantic layer that sits between your raw database schema and the report builder. It translates technical database fields into business-friendly terminology, defines the relationships between tables, and controls what data is accessible to builders.
You build this once. After that, your report builders work entirely in business terms — no SQL required. Getting this layer right is what makes Yurbi feel effortless for your users.
Create report types
Group your data into meaningful categories — "Orders," "Customers," "Support Tickets." Each report type maps to a set of database tables and defines a context for report building. Think about how your users talk about their data, not how your database is structured.
Add tables and define relationships
For each report type, add the database tables it draws from and define the joins. This is your ERD mapping in Yurbi terms. Unjoined tables produce invalid SQL — the Architect validates this for you.
Build the field tree
Select which database fields are exposed, rename them to business-friendly display names, organize them into folders, and set data types. This is also where you fix type mismatches — API sources especially often deliver everything as text, requiring explicit casting.
Add formula fields
Virtual fields — calculations, date transformations, concatenations, conditional expressions — that don't exist in your raw schema but matter to your users. "Days Since Last Login," "Quarter Label," "Full Name" — these live in the semantic layer, not your database.
Alternative: skip the semantic layer with direct SQL
If your team is technical and you just need to embed pre-built reports quickly — not give end users an ad-hoc builder — you can bypass the Architect entirely. Write SQL queries directly to build datasets, then use Advanced Reports → Virtual App to turn those datasets into charts, grids, and formulas.
This path trades flexibility for speed. It works well for internal teams that know their database and want to get dashboards in front of users fast. It also fits the specific case where each tenant has their own separate database and raw SQL per-tenant is manageable.
What it doesn't support: the no-code report builder for end users. If you want customers to build their own reports without writing SQL, the semantic layer is still the right approach. For embedded ISV deployments where you control all the report content, direct SQL is a legitimate shortcut.
Configure Security
For internal BI tools, security configuration is straightforward — create users, assign roles, done. For ISV and multi-tenant deployments, this phase requires careful planning. The goal: every customer sees their own data, and only their data, regardless of what report they run.
Users, groups & roles
Create security groups matching your tenant structure. Assign users to groups. Set roles per data source — Agent for view-only customers, Builder for self-service analytics. Admin and Architect roles stay with your internal team.
Roles are per-app. The same user can be an Agent in your customer-facing app and a Builder in an internal one.
Tenant Mode
Enable Tenant Mode in Server Settings for any multi-tenant deployment. This filters security group lists, removes the "All Users" group from tenant-facing views, and restricts the scheduling contact list to each tenant's own users.
Without Tenant Mode, tenants can see each other's group names. With it — nothing bleeds across.
App Shield — data-level security
App Shield is the security layer that ensures Customer A never sees Customer B's rows, even when running the same report. You define field-level constraints (e.g., "filter by CustomerID = this user's assigned ID"), attach the policy to a security group, and Yurbi enforces it at query time — embedded directly into every SQL call.
Set once. Enforced on every report, dashboard, scheduled email, and embedded view — automatically. This is the step that makes multi-tenant embedded analytics safe to ship.
Build Reports & Dashboards
With your data connected and security configured, you're ready to build the analytics content your customers will actually use. Yurbi's report builder is no-code — your team selects fields, applies filters, chooses visualization types, and publishes. No SQL, no front-end code required.
Start with the datagrid
The datagrid (tabular report) is the foundation. Build your core reports here first — it establishes the field selections, sorting, and filters that other visualization types build on. Every other report type starts from the same building blocks.
20+ visualization types
Bar, line, area, pie, donut, gauge, scatter, map, combo charts — plus custom JS/CSS visualizations for anything the standard library doesn't cover. The Gallery shows the full range: view the visualization gallery →
Dashboards & filters
Combine reports into dashboards with shared filters — your customers can slice and dice across all panels at once. Dashboard Smart Filters create dynamic filter lists from your data. Saved views let users preserve their preferred filter state.
FastCache for performance
For dashboards that will be hit by many concurrent users, enable FastCache — in-memory caching that serves pre-computed results instead of re-querying your database on every load. Configure cache duration per dashboard. FastCache details →
Embed in Your Product
This is what you've been building toward. Yurbi embeds into your application via a session token system — your backend authenticates the user silently, receives a token, and passes it to an embed URL. Your customers land on their analytics without ever seeing a Yurbi login screen.
Full Yurbi interface access
You can also use the session token to deep-link users directly into the Yurbi interface — dashboard view, report library, or builder — via sso.html?s={token}. Useful when you want to give Builder-role users access to build their own reports inside your application.
White-label branding
Configure Yurbi's branding per tenant — logo, colors, application name. Your customers see your brand, not Yurbi's. Branding is applied in the Admin panel and takes effect immediately. Embedding & white-label details →
Go Live
The final phase is less technical than it sounds. Apply your production license key (the same process as trial activation), confirm your backup strategy, and hand off to the team who will manage ongoing administration.
Production license
Every plan includes 1 Development + 1 Production license. Apply the production key via the same activation panel used during install. Trial data, reports, and configuration survive — nothing is deleted.
Backup strategy
Back up your Yurbi installation database (PostgreSQL or MS SQL) on the same schedule as your other critical systems. This preserves all reports, users, permissions, and configuration. The installation directory contains configuration files worth backing up too.
Ongoing upgrades
Yurbi ships weekly releases. Upgrading is an in-place installer run — typically under 15 minutes. All plan tiers include all upgrades for the life of an active subscription. Subscribe to the changelog to know what shipped.
We can do the implementation for you.
If you'd rather not spend your team's time on Phases 4 and 5 — the semantic layer build and security configuration — our Done-For-You services handle it. We've implemented Yurbi across hundreds of deployments. We know the patterns, the edge cases, and the fast path.
Implementation questions.
Install through first embedded dashboard typically takes one to two weeks for an experienced team — most of that time is in Phases 4 and 5 (semantic layer and security), which depend on the complexity of your database schema and your tenant structure. Teams with simpler schemas and a single-tenant setup often finish in days. Complex multi-tenant ISV deployments with many report types can take longer. The 14-day trial is usually enough to complete a meaningful proof of concept — extensions are freely given, just ask.
For Phases 1–3 (prerequisites, install, data connection) and Phase 7 (embedding): yes, you need someone comfortable with server administration and basic API calls. For Phases 4–6 (semantic layer, security, reports): the work is technical but not coding-heavy — it requires understanding your database schema and your business requirements. The Architect tool is a UI, not a code editor. Many teams use a technical analyst or DBA for this phase rather than a developer. Phase 7 (embedding) requires a developer who can make an API call and place an iframe.
Yes. Yurbi connects to the same databases those tools use, so the data access layer is already there. The implementation work is mostly the same as a greenfield deployment — you build the semantic layer in Yurbi against your existing database schema, then rebuild your reports in Yurbi's builder. There's no automated migration of report definitions from legacy tools, but rebuilding reports in Yurbi is typically much faster than maintaining them was in the old tool. Our services team has done this migration many times. Legacy replacement details →
Nothing is deleted when a trial expires. Your reports, users, configuration, and data connections all survive. Just email support@yurbi.com and ask for an extension — we give them freely without requiring a purchase decision. We'd rather you have enough time to evaluate properly.
Yes — assign them the Builder role instead of Agent. They'll see a simplified version of the Yurbi App scoped to the fields and report types you've made available to them, and they can build their own reports within those boundaries. App Shield policies apply to everything they build, so they can only access rows they're authorized to see. This is how most ISVs offer self-service analytics without exposing full data access.
Yurbi ships weekly releases. Upgrading is an in-place installer run on your server — typically 10–15 minutes with a brief downtime window. All plans include upgrades for the life of an active subscription. We recommend subscribing to the changelog at roadmap.yurbi.com/announcements so you know what's in each release before applying it.