Skip to main content

​
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
monk load MANIFEST
  1. Run Metabase with defaults
monk run metabase/metabase
  1. 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: 
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. Inherit the Metabase runnable in your data stack and declare a connection. Example: 
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: 
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
  • 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:
openssl rand -hex 16
  • Check logs:
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.