Installation

Install Metabase using Docker, JAR file, or Metabase Cloud.

Installation

Metabase can run anywhere Java runs. Choose the installation method that best fits your needs.

Metabase Cloud

Managed hosting with automatic upgrades

Docker

Recommended for self-hosting

JAR file

Direct Java deployment

Metabase Cloud

Recommended - The easiest way to run Metabase with none of the operational overhead.

Metabase Cloud is the fastest way to get started:

• Up and running in minutes - No installation or setup required
• Automatic upgrades - Always on the latest version
• Managed infrastructure - High availability, backups, and monitoring included
• Built-in SMTP server - Email and Slack notifications work out of the box
• SSL certificate - Secure HTTPS by default
• SOC 2 Type 2 certified - Enterprise-grade security
• Expert support - Email support with SLA

1. Sign up

   Start a free trial - No credit card required.

2. Connect your database

   Add your database connection details.

3. Start exploring

   Begin asking questions and building dashboards immediately.

Your money goes toward improving Metabase rather than paying cloud infrastructure providers. Plus, you can always migrate to self-hosting if your needs change.

Docker installation

Recommended for self-hosting - Docker provides consistent deployments across all platforms.

Docker is the easiest way to self-host Metabase.

Requirements

• Docker installed and running
• 2GB of RAM minimum (4GB+ recommended)
• Java 21 (included in Docker image)

Quick start (local development)

For testing and local development:

Open Source edition

# Pull the latest image
docker pull metabase/metabase:latest

# Start Metabase
docker run -d -p 3000:3000 --name metabase metabase/metabase

Access Metabase at http://localhost:3000.

To view logs: docker logs -f metabase

Production installation

The quick start setup uses an embedded H2 database that stores data inside the container. If you delete the container, you’ll lose all your questions, dashboards, and settings.

For production, use a dedicated application database.

Step 1: Set up an application database

Metabase needs a database to store its application data (questions, dashboards, users, etc.).

Supported databases:

• PostgreSQL (recommended)
• MySQL / MariaDB

Create an empty database:

PostgreSQL

CREATE DATABASE metabaseappdb;

Metabase will create all necessary tables automatically. You just need to provide an empty database.

Step 2: Run with environment variables

Tell Metabase how to connect to your application database:

docker run -d -p 3000:3000 \
  -e "MB_DB_TYPE=postgres" \
  -e "MB_DB_DBNAME=metabaseappdb" \
  -e "MB_DB_PORT=5432" \
  -e "MB_DB_USER=metabase" \
  -e "MB_DB_PASS=your_secure_password" \
  -e "MB_DB_HOST=your-database-host" \
  --name metabase metabase/metabase

Replace your-database-host with:

• Your database’s hostname or IP address
• host.docker.internal if the database runs on the same machine (Mac/Windows)
• The service name if using Docker Compose

Step 3: Use Docker Compose (recommended)

Create a docker-compose.yml file:

docker-compose.yml

services:
  metabase:
    image: metabase/metabase:latest
    container_name: metabase
    hostname: metabase
    ports:
      - 3000:3000
    environment:
      MB_DB_TYPE: postgres
      MB_DB_DBNAME: metabaseappdb
      MB_DB_PORT: 5432
      MB_DB_USER: metabase
      MB_DB_PASS: mysecretpassword
      MB_DB_HOST: postgres
    networks:
      - metanet
    depends_on:
      - postgres
    healthcheck:
      test: curl --fail -I http://localhost:3000/api/health || exit 1
      interval: 15s
      timeout: 5s
      retries: 5
      
  postgres:
    image: postgres:16
    container_name: postgres
    hostname: postgres
    environment:
      POSTGRES_USER: metabase
      POSTGRES_DB: metabaseappdb
      POSTGRES_PASSWORD: mysecretpassword
    volumes:
      - ./pg_data:/var/lib/postgresql/data
    networks:
      - metanet
      
networks:
  metanet:
    driver: bridge

Start everything:

docker compose up -d

This configuration keeps your data in ./pg_data on your host machine, making it easy to backup and persist across container restarts.

Advanced Docker configuration

Using Docker Secrets

For sensitive credentials, use Docker secrets instead of environment variables:

services:
  metabase:
    image: metabase/metabase:latest
    environment:
      MB_DB_TYPE: postgres
      MB_DB_DBNAME: metabase
      MB_DB_PORT: 5432
      MB_DB_USER_FILE: /run/secrets/db_user
      MB_DB_PASS_FILE: /run/secrets/db_password
      MB_DB_HOST: postgres
    secrets:
      - db_password
      - db_user
      
secrets:
  db_password:
    file: db_password.txt
  db_user:
    file: db_user.txt

Create db_user.txt and db_password.txt with your credentials.

Setting timezone

Set the Java timezone to match your reporting timezone:

docker run -d -p 3000:3000 \
  -e "JAVA_TIMEZONE=US/Pacific" \
  --name metabase metabase/metabase

Adding plugins and drivers

Mount a plugins directory for JDBC drivers or custom plugins:

docker run -d -p 3000:3000 \
  --mount type=bind,source=/path/to/plugins,destination=/plugins \
  --name metabase metabase/metabase

The plugins directory must be readable and writable by Docker. Metabase uses it to extract bundled drivers.

Persisting data with volumes

Mount a volume for the H2 database (development only):

docker run -d -p 3000:3000 \
  -v ~/metabase-data:/metabase-data \
  -e "MB_DB_FILE=/metabase-data/metabase.db" \
  --name metabase metabase/metabase

JAR file installation

We recommend Docker for self-hosting. The JAR file is easier to get started but more challenging to run in production.

The JAR file runs anywhere Java runs.

Requirements

• Java 21 or later (we recommend Eclipse Temurin)
• 2GB of RAM minimum (4GB+ recommended)

Quick start (local development)

1. Install Java

   Check if Java is installed:

   java -version
   

   If not installed, download Java 21 from Eclipse Temurin.

2. Download Metabase

   Download the JAR file:

   • Metabase OSS
   • Metabase Enterprise/Pro
3. Create a directory

   Move the JAR to a new directory:

   mkdir ~/metabase
   mv ~/Downloads/metabase.jar ~/metabase/
   cd ~/metabase
   
4. Run Metabase

   Start Metabase:

   java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar
   

   Wait for “Metabase Initialization COMPLETE” in the logs.

5. Open Metabase

   Access Metabase at http://localhost:3000.

Production installation

For production, you need:

1. A production application database
2. To run Metabase as a service

Step 1: Set up an application database

Create an empty PostgreSQL or MySQL database:

CREATE DATABASE metabaseappdb;

Step 2: Configure environment variables

Set environment variables before running the JAR:

export MB_DB_TYPE=postgres
export MB_DB_DBNAME=metabaseappdb
export MB_DB_PORT=5432
export MB_DB_USER=metabase
export MB_DB_PASS=your_secure_password
export MB_DB_HOST=localhost

java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

Step 3: Run as a service

For production, run Metabase as a system service:

• Ensures Metabase stays running and restarts automatically
• Runs with an unprivileged user for better security
• Manages environment variables in a configuration file

Example systemd service file:

/etc/systemd/system/metabase.service

[Unit]
Description=Metabase
After=network.target

[Service]
User=metabase
Group=metabase
WorkingDirectory=/opt/metabase
Environment="MB_DB_TYPE=postgres"
Environment="MB_DB_DBNAME=metabaseappdb"
Environment="MB_DB_PORT=5432"
Environment="MB_DB_USER=metabase"
Environment="MB_DB_PASS=your_secure_password"
Environment="MB_DB_HOST=localhost"
ExecStart=/usr/bin/java --add-opens java.base/java.nio=ALL-UNNAMED -jar /opt/metabase/metabase.jar
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable metabase
sudo systemctl start metabase
sudo systemctl status metabase

For detailed instructions, see Running Metabase as a systemd service.

Other installation options

Podman

Run Metabase using Podman instead of Docker

Azure Web Apps

Deploy to Azure App Service

Build from source

Compile Metabase yourself

Air-gapped environments

Run Metabase without internet access

Metabase doesn’t have official distributions on:

• AWS Marketplace or Azure Marketplace
• Helm charts (community charts exist but aren’t officially supported)

Migrating from H2 to production

If you started with the default H2 database and now want to move to production:

1. Create a production database

   Set up PostgreSQL or MySQL and create an empty database.

2. Migrate your data

   Use the migration tool to move your application data:

   export MB_DB_TYPE=postgres
   export MB_DB_DBNAME=metabaseappdb
   export MB_DB_PORT=5432
   export MB_DB_USER=metabase
   export MB_DB_PASS=password
   export MB_DB_HOST=localhost
   
   java -jar metabase.jar load-from-h2 /path/to/metabase.db
   
3. Verify the migration

   Start Metabase with the new database and verify all your content is present.

For detailed migration instructions, see Migrating from H2.

Next steps

After installation:

1. Set up Metabase

   Complete the initial setup wizard to create your admin account and connect your first database.

   Setup guide →

2. Activate your license (if applicable)

   If you’re using Pro or Enterprise edition, activate your license.

   License activation →

3. Configure email

   Set up SMTP so Metabase can send alerts and subscriptions.

   Email setup →

4. Invite your team

   Add users and set up permissions.

   User management →

Troubleshooting

Metabase won't start

Check the logs for error messages:

Docker:

docker logs metabase

JAR: Check the terminal output or log file.

Common issues:

• Port already in use - Change the port with MB_JETTY_PORT
• Out of memory - Increase JVM heap size
• Database connection failed - Verify database credentials

Database connection issues

Verify:

• Database server is running and accessible
• Credentials are correct
• Firewall allows the connection
• Network connectivity (use telnet or nc to test)

For Docker:

• Use host.docker.internal for databases on the host machine
• Use service names in Docker Compose networks

Performance issues

• Increase memory allocation (4GB+ recommended)
• Use a production application database (not H2)
• Enable caching in Admin → Settings
• Add indexes to your data warehouse

For more help, see the troubleshooting guide or visit the community forum.

Getting help

Need assistance with installation?

• Community forum - Free community support
• Metabase Experts - Professional services
• Enterprise support - Dedicated support for Pro and Enterprise customers