Running the Metabase JAR file

The Metabase JAR file allows you to run Metabase directly on any system with Java installed. While Docker is recommended for production, the JAR provides more control and is useful for specific deployment scenarios.

For easier deployment and management, we recommend Docker for production. For the easiest option, use Metabase Cloud.

When to use the JAR

The JAR file is ideal for:

Testing and local development
Environments where Docker isn’t available
Custom deployment scenarios requiring direct Java control
Integration with existing Java application servers
Running on systems with restricted container support

Prerequisites

Java requirements

Java 21 is required. Earlier versions are not supported.

We recommend:

Java 21 JRE from Eclipse Temurin with HotSpot JVM
Works on x86 and ARM architectures
Linux, macOS, and Windows are supported

Check your Java version

java -version

Expected output:

openjdk version "21.0.1" 2023-10-17
OpenJDK Runtime Environment Temurin-21.0.1+12 (build 21.0.1+12)
OpenJDK 64-Bit Server VM Temurin-21.0.1+12 (build 21.0.1+12, mixed mode, sharing)

Quick start (local testing)

Get Metabase running quickly for testing and demos:

Download Metabase

Open Source
Pro/Enterprise

Download the Metabase OSS JAROr via command line:

wget https://downloads.metabase.com/v0.54.1/metabase.jar

Download the Metabase Enterprise JAROr via command line:

wget https://downloads.metabase.com/enterprise/v0.54.1/metabase.jar

Create a directory

Create a dedicated directory for Metabase (important for H2 database files):

mkdir ~/metabase
mv metabase.jar ~/metabase/
cd ~/metabase

Run Metabase

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

The --add-opens flag is required for Java 9+.

Access Metabase

Once you see “Metabase Initialization Complete”, visit:http://localhost:3000Complete the setup wizard to create your admin account.

Understanding the startup logs

You’ll see logs like:

2024-03-02 10:29:34 INFO metabase.core :: Starting Metabase version v0.54.1
2024-03-02 10:29:35 INFO metabase.db :: Setting up database...
2024-03-02 10:29:38 INFO metabase.core :: Metabase Initialization COMPLETE

Wait for “Metabase Initialization COMPLETE” before accessing.

Using a different port

By default, Metabase runs on port 3000. To use a different port:

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

Access at http://localhost:8080

Production installation

Do not use the default H2 database for production. Set up PostgreSQL or MySQL for your application database.

For production deployments, you need:

A production-ready application database (PostgreSQL or MySQL)
Process management (systemd, supervisor, or similar)
Reverse proxy (nginx, Apache) for SSL/TLS
Regular backups
Monitoring and logging

Set up the application database

PostgreSQL
MySQL

Create an empty database:

createdb --encoding=UTF8 -e metabaseappdb

Configure environment variables:

export MB_DB_TYPE=postgres
export MB_DB_DBNAME=metabaseappdb
export MB_DB_PORT=5432
export MB_DB_USER=metabase_user
export MB_DB_PASS=secure_password
export MB_DB_HOST=localhost

Create a database:

CREATE DATABASE metabaseappdb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Configure environment variables:

export MB_DB_TYPE=mysql
export MB_DB_DBNAME=metabaseappdb
export MB_DB_PORT=3306
export MB_DB_USER=metabase_user
export MB_DB_PASS=secure_password
export MB_DB_HOST=localhost

Learn more about configuring the application database

Run with production database

export MB_DB_TYPE=postgres
export MB_DB_DBNAME=metabaseappdb
export MB_DB_PORT=5432
export MB_DB_USER=metabase_user
export MB_DB_PASS=secure_password
export MB_DB_HOST=localhost
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

Metabase will create all necessary tables on first startup.

Running as a system service

For production, run Metabase as a systemd service for automatic startup and management.

Create a systemd service

Create metabase user

sudo useradd -r -s /bin/false metabase

Set up directories

sudo mkdir -p /opt/metabase
sudo cp metabase.jar /opt/metabase/
sudo chown -R metabase:metabase /opt/metabase

Create environment file

Create /etc/default/metabase:

MB_DB_TYPE=postgres
MB_DB_DBNAME=metabaseappdb
MB_DB_PORT=5432
MB_DB_USER=metabase_user
MB_DB_PASS=secure_password
MB_DB_HOST=localhost

MB_JETTY_HOST=0.0.0.0
MB_JETTY_PORT=3000

JAVA_OPTS="-Xmx2g"

Secure the file:

sudo chmod 600 /etc/default/metabase
sudo chown metabase:metabase /etc/default/metabase

Create service file

Create /etc/systemd/system/metabase.service:

[Unit]
Description=Metabase Analytics Server
After=network.target

[Service]
Type=simple
User=metabase
Group=metabase
EnvironmentFile=/etc/default/metabase
WorkingDirectory=/opt/metabase
ExecStart=/usr/bin/java --add-opens java.base/java.nio=ALL-UNNAMED -jar /opt/metabase/metabase.jar
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=metabase

[Install]
WantedBy=multi-user.target

Enable and start service

sudo systemctl daemon-reload
sudo systemctl enable metabase
sudo systemctl start metabase

Check status

sudo systemctl status metabase
sudo journalctl -u metabase -f

Manage the service

sudo systemctl start metabase

Configuration options

Memory settings

Set Java heap size for optimal performance:

export JAVA_OPTS="-Xmx4g"  # 4GB max heap
java $JAVA_OPTS --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

Recommended heap sizes:

Small deployments: 2GB (-Xmx2g)
Medium deployments: 4GB (-Xmx4g)
Large deployments: 8GB+ (-Xmx8g)

Timezone configuration

Set timezone for reports and queries:

export JAVA_TIMEZONE=US/Pacific
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

Binding address

Listen on all interfaces (required for remote access):

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

SSL/HTTPS configuration

Enable HTTPS directly in Metabase:

export MB_JETTY_SSL=true
export MB_JETTY_SSL_PORT=8443
export MB_JETTY_SSL_KEYSTORE=/path/to/keystore.jks
export MB_JETTY_SSL_KEYSTORE_PASSWORD=keystorepassword
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

For production, we recommend using a reverse proxy (nginx, Apache) for SSL instead of Metabase’s built-in SSL.

All environment variables

See the complete list of configuration options:

Environment variables reference

Complete guide to all Metabase configuration options

Upgrading Metabase

Back up your database

Always back up before upgrading:

# PostgreSQL
pg_dump -h localhost -U metabase_user metabaseappdb > backup.sql

# MySQL
mysqldump -u metabase_user -p metabaseappdb > backup.sql

Learn more about backing up

Stop Metabase

# If running as service
sudo systemctl stop metabase

# If running manually
# Press Ctrl+C to stop

Download new version

wget https://downloads.metabase.com/v0.54.1/metabase.jar -O metabase-new.jar

Replace JAR file

# Backup old JAR
mv /opt/metabase/metabase.jar /opt/metabase/metabase.jar.backup

# Install new JAR
mv metabase-new.jar /opt/metabase/metabase.jar
sudo chown metabase:metabase /opt/metabase/metabase.jar

Start Metabase

sudo systemctl start metabase

Monitor logs for successful startup:

sudo journalctl -u metabase -f

Metabase will automatically run database migrations on startup.

Full upgrade guide

Complete upgrade documentation with troubleshooting

Reverse proxy configuration

For production deployments, use a reverse proxy for SSL and better security.

Nginx example

server {
    listen 80;
    server_name analytics.company.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name analytics.company.com;
    
    ssl_certificate /etc/ssl/certs/metabase.crt;
    ssl_certificate_key /etc/ssl/private/metabase.key;
    
    # SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    
    # Increase timeouts for long-running queries
    proxy_connect_timeout 300;
    proxy_send_timeout 300;
    proxy_read_timeout 300;
    send_timeout 300;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Apache example

<VirtualHost *:80>
    ServerName analytics.company.com
    Redirect permanent / https://analytics.company.com/
</VirtualHost>

<VirtualHost *:443>
    ServerName analytics.company.com
    
    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/metabase.crt
    SSLCertificateKeyFile /etc/ssl/private/metabase.key
    
    ProxyPreserveHost On
    ProxyPass / http://localhost:3000/
    ProxyPassReverse / http://localhost:3000/
    
    # WebSocket support
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/?(.*) "ws://localhost:3000/$1" [P,L]
    
    # Increase timeout for long queries
    ProxyTimeout 300
</VirtualHost>

Troubleshooting

Port already in use

# Find process using port 3000
lsof -i :3000

# Kill the process or use a different port
export MB_JETTY_PORT=8080

Out of memory errors

Increase Java heap size:

export JAVA_OPTS="-Xmx4g"
java $JAVA_OPTS --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

Can’t connect to database

Verify database is running: pg_isready or mysqladmin ping
Check credentials in environment variables
Test connection: psql -h localhost -U metabase_user metabaseappdb
Check firewall rules

Slow startup

Check available memory
Verify database performance
Review logs for errors: journalctl -u metabase
Increase timeout for database operations

Best practices

Use a production database

Never use H2 in production. Configure PostgreSQL or MySQL.

Run as a service

Use systemd or similar for automatic startup and process management.

Set up SSL/TLS

Use a reverse proxy (nginx, Apache) for HTTPS.

Configure backups

Implement regular database backups and test restoration.

Monitor resources

Track CPU, memory, and database performance.

Set appropriate memory

Allocate sufficient heap size based on usage.

Use a dedicated user

Run Metabase as an unprivileged user for security.

Centralize logs

Forward logs to a logging system for monitoring.

Migrating from H2 to production

If you’ve been using the default H2 database and need to migrate:

Migrate from H2

Complete guide to migrating your data to PostgreSQL or MySQL

Next steps

Configure database

Set up PostgreSQL or MySQL for production

Environment variables

Complete configuration reference

Backing up

Implement backup procedures

Upgrading

Learn how to upgrade Metabase safely

Getting Started

Questions & Dashboards

Data Modeling

Database Connections

Embedding

Administration

Installation & Operations

AI Features

Documentation Index

​When to use the JAR

​Prerequisites

​Java requirements

​Check your Java version

​Quick start (local testing)

​Understanding the startup logs

​Using a different port

​Production installation

​Set up the application database

​Run with production database

​Running as a system service

​Create a systemd service

​Manage the service

​Configuration options

​Memory settings

​Timezone configuration

​Binding address

​SSL/HTTPS configuration

​All environment variables

Environment variables reference

​Upgrading Metabase

Full upgrade guide

​Reverse proxy configuration

​Nginx example

​Apache example

​Troubleshooting

​Port already in use

​Out of memory errors

​Can’t connect to database

​Slow startup

​Best practices

​Migrating from H2 to production

Migrate from H2

​Next steps

Configure database

Environment variables

Backing up

Upgrading

When to use the JAR

Prerequisites

Java requirements

Check your Java version

Quick start (local testing)

Understanding the startup logs

Using a different port

Production installation

Set up the application database

Run with production database

Running as a system service

Create a systemd service

Manage the service

Configuration options

Memory settings

Timezone configuration

Binding address

SSL/HTTPS configuration

All environment variables

Upgrading Metabase

Reverse proxy configuration

Nginx example

Apache example

Troubleshooting

Port already in use

Out of memory errors

Can’t connect to database

Slow startup

Best practices

Migrating from H2 to production

Next steps