> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Metabase

> Ready-to-run Metabase container template for business intelligence and data visualization with no SQL required.

## Overview

This template provides a production‑ready Metabase instance as a Monk runnable. You can:

* Run it directly to get a managed business intelligence platform
* Inherit it in your own data stack to add self-service analytics and visualization

Metabase is the easy, open-source way for everyone in your company to ask questions and learn from data. It's simple enough for non-technical users yet powerful enough for data analysts.

## What this template manages

* Metabase application server
* PostgreSQL or H2 application database
* Web UI and API
* Query builder and SQL editor
* Dashboard and visualization engine
* Web UI on port 3000

## Quick start (run directly)

1. Load templates

```bash theme={null}
monk load MANIFEST
```

2. Run Metabase with defaults

```bash theme={null}
monk run metabase/metabase
```

3. Customize credentials (recommended via inheritance)

Running directly uses the defaults defined in this template's `variables`. Secrets added with `monk secrets add` will not affect this runnable unless you inherit it and reference those secrets.

* Preferred: inherit and replace variables with `secret("...")` as shown below.
* Alternative: fork/clone and edit the `variables` in `metabase.yaml`, then `monk load MANIFEST` and run.

Once started, access Metabase at `http://localhost:3000` and complete the setup wizard to create your admin account and connect data sources.

## Configuration

Key variables you can customize in this template:

```yaml theme={null}
variables:
  # Metabase
  metabase-image-tag: "latest"        # Metabase image tag
  metabase-port: "3000"               # web UI port
  
  # Application Database
  mb-db-type: "postgres"              # postgres or h2
  mb-db-host: "postgres"              # database host
  mb-db-port: "5432"                  # database port
  mb-db-dbname: "metabase"            # database name
  mb-db-user: "metabase"              # database user
  mb-db-pass: "..."                   # database password
  
  # Optional
  java-timezone: "UTC"                # JVM timezone
  mb-encryption-secret-key: "..."     # encryption key for app DB
```

Data is persisted under `${monk-volume-path}/metabase` on the host and `${monk-volume-path}/postgres` for PostgreSQL data.

## Use by inheritance (recommended for BI)

Inherit the Metabase runnable in your data stack and declare a connection. Example:

```yaml theme={null}
namespace: mycompany
analytics:
  defines: runnable
  inherits: metabase/metabase
  variables:
    mb-db-pass:
      value: <- secret("metabase-db-password")
    mb-encryption-secret-key:
      value: <- secret("metabase-encryption-key")
datawarehouse:
  defines: runnable
  containers:
    dw:
      image: myorg/datawarehouse
  connections:
    bi:
      runnable: analytics
      service: metabase
```

Then set the secrets once and run your stack:

```bash theme={null}
monk secrets add -g metabase-db-password="STRONG_PASSWORD"
monk secrets add -g metabase-encryption-key="<random-key>"
monk run mycompany/analytics
```

## Ports and connectivity

* Service: `metabase` on TCP port `3000`
* From other runnables in the same process group, use `connection-hostname("\<connection-name>")` to resolve the Metabase host.
* Metabase connects to your data sources (configure in UI)

## Persistence and configuration

* H2 database (if used): `${monk-volume-path}/metabase/data:/metabase-data`
* PostgreSQL data: `${monk-volume-path}/postgres:/var/lib/postgresql/data`

## Features

* **No-Code Query Builder**: Ask questions without SQL
* **SQL Editor**: For power users who need custom queries
* **Visualizations**: 15+ chart types (line, bar, pie, maps, etc.)
* **Interactive Dashboards**: Combine multiple questions into dashboards
* **Automated Reports**: Email dashboards on a schedule
* **Data Sources**: 20+ databases (PostgreSQL, MySQL, MongoDB, BigQuery, etc.)
* **Permissions**: Control who sees what data
* **Embedding**: Embed dashboards in your apps
* **Alerts**: Get notified when metrics change

## Connecting Data Sources

Metabase supports many databases:

* **SQL**: PostgreSQL, MySQL, MariaDB, SQL Server
* **Cloud**: BigQuery, Redshift, Snowflake, Athena
* **NoSQL**: MongoDB, DynamoDB
* **Analytics**: Druid, Presto
* **And many more...**

Add database in Admin → Databases → Add database

## Building Questions

Three ways to ask questions:

1. **Simple Question**: Point-and-click query builder
2. **Custom Question**: Visual query builder with joins, filters
3. **Native Query**: Write SQL directly

## Dashboards

Create interactive dashboards:

* Add multiple questions/visualizations
* Add filters for interactivity
* Auto-refresh dashboards
* Share via link or email
* Embed in external apps

## Use cases

Metabase excels at:

* Self-service business intelligence
* Executive dashboards
* Operational reporting
* Data exploration and discovery
* Automated report delivery
* Embedded analytics in SaaS apps
* Team data democratization

## Related templates

* Connect to data warehouses: `postgresql/`, `clickhouse/`, etc.
* Use with ETL tools: `airflow/`, `dagster/`
* Integrate with data pipelines for reporting

## Troubleshooting

* Access Metabase UI at `http://localhost:3000`
* Generate encryption key:

```bash theme={null}
openssl rand -hex 16
```

* Check logs:

```bash theme={null}
monk logs -l 500 -f metabase/metabase
```

* If you changed database credentials but the container has existing data, authentication may fail. Either reset the data volume or update credentials inside the DB to match.
* For slow queries, check database connection and query performance.
* For data source connection issues, verify credentials and network access.
* For memory issues, increase Java heap size with `JAVA_OPTS` environment variable.
* Use PostgreSQL instead of H2 for production (better performance and reliability).
* First startup can take 2-3 minutes while Metabase initializes the database schema.