Running Metabase on Docker

Deploy Metabase using Docker containers for easy installation, updates, and consistent environments across systems.

Metabase provides official Docker images via Docker Hub for easy deployment on any system running Docker. This is the recommended way to self-host Metabase.

For fast, reliable deployment without any management overhead, consider Metabase Cloud instead of self-hosting.

Why use Docker?

Docker provides several advantages for running Metabase:

• Easy deployment - Single command to get started
• Consistent environment - Works the same everywhere
• Simple updates - Pull new images and restart
• Isolated process - Clean separation from host system
• Built-in process management - Automatic restarts
• Environment-based configuration - No file editing needed

Quick start (Open Source)

Get Metabase Open Source running locally in minutes:

1. Pull the latest image

   docker pull metabase/metabase:latest
   
2. Start Metabase

   docker run -d -p 3000:3000 --name metabase metabase/metabase
   

   This starts Metabase on port 3000 with the default H2 database.

3. Access Metabase

   Open your browser to http://localhost:3000 and complete the setup wizard.

View logs

Monitor Metabase startup and operations:

docker logs -f metabase

Wait for “Metabase Initialization Complete” before accessing.

Custom port

Run on a different port (e.g., port 12345):

docker run -d -p 12345:3000 --name metabase metabase/metabase

Access at http://localhost:12345

Quick start (Pro/Enterprise)

If you have a license token for Pro or Enterprise:

1. Pull the Enterprise image

   docker pull metabase/metabase-enterprise:latest
   
2. Start Metabase Enterprise

   docker run -d -p 3000:3000 --name metabase metabase/metabase-enterprise
   
3. Access and activate

   Open http://localhost:3000 and activate your license.

Production installation

The quick start uses the default H2 database, which is not suitable for production. You’ll lose all your data if you remove the container.

For production deployments, use a production-ready database (PostgreSQL or MySQL) to store Metabase’s application data.

Set up a production database

PostgreSQL

First, create an empty PostgreSQL database:

createdb metabaseappdb

Metabase will create all necessary tables automatically.

MySQL

Create a MySQL database with the correct character set:

CREATE DATABASE metabaseappdb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Run with production database

Provide database connection details via environment variables:

PostgreSQL

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=username" \
  -e "MB_DB_PASS=password" \
  -e "MB_DB_HOST=my-database-host" \
  --name metabase metabase/metabase

Metabase connects from inside the Docker container. Use fully qualified hostnames or configure /etc/hosts in the container.

Docker Compose (recommended for production)

Use Docker Compose to manage Metabase and its database together:

docker-compose.yml

services:
  metabase:
    image: metabase/metabase:v0.54.1
    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 with:

docker compose up -d

This is an example configuration. For production, see our production deployment guide.

Volume management

Mounting a data volume

Persist H2 data or custom files by mounting a volume:

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

The database file will be stored at ~/metabase-data/metabase.db on your host.

Mounting plugins directory

Add custom JDBC drivers or plugins:

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

Place JAR files in /path/to/plugins on your host system.

The plugins directory must be readable and writable by Docker. Metabase extracts bundled drivers here.

Configuration

Java timezone

Set the timezone for report generation:

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

Custom user/group IDs

Match file permissions with host system:

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

Additional server settings

All environment variables can be passed with -e:

docker run -d -p 3000:3000 \
  -e "MB_SITE_NAME=Company Analytics" \
  -e "MB_SITE_URL=https://analytics.company.com" \
  -e "MB_EMAIL_SMTP_HOST=smtp.gmail.com" \
  -e "MB_EMAIL_SMTP_PORT=587" \
  --name metabase metabase/metabase

Using Docker secrets

Keep sensitive values secure with Docker secrets:

docker-compose.yml

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_user
      - db_password

  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER_FILE: /run/secrets/db_user
      POSTGRES_DB: metabase
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_user
      - db_password

secrets:
  db_user:
    file: db_user.txt
  db_password:
    file: db_password.txt

Create text files with credentials:

echo "metabase_user" > db_user.txt
echo "secure_password" > db_password.txt
chmod 600 db_*.txt

Supported secret variables:

• MB_DB_USER_FILE
• MB_DB_PASS_FILE
• MB_DB_CONNECTION_URI_FILE
• MB_EMAIL_SMTP_PASSWORD_FILE
• MB_EMAIL_SMTP_USERNAME_FILE
• MB_LDAP_PASSWORD_FILE
• MB_LDAP_BIND_DN_FILE

Managing containers

Stop Metabase

docker stop metabase

Start stopped container

docker start metabase

Restart Metabase

docker restart metabase

Remove container

docker rm metabase

Removing a container with H2 database will delete all your data unless you mounted a volume.

View running containers

docker ps

View all containers (including stopped)

docker ps -a

Recovering from stopped container

If you stopped a container and want to recover your configuration:

1. Find the stopped container

   docker ps -a | grep metabase
   

   Note the container ID (e.g., ca072cd44a49).

2. Create a custom image

   docker commit ca072cd44a49 mycompany/metabase-custom
   
3. Run your custom image

   docker run -d -p 3000:3000 --name metabase mycompany/metabase-custom
   

Copying the H2 database file

If you need to backup or inspect the H2 database:

docker cp metabase:/metabase.db/metabase.db.mv.db ./metabase_backup.mv.db

The database file will be copied to your current directory.

Migrate from H2 to production

Learn how to migrate from H2 to PostgreSQL or MySQL

Upgrading Metabase

Upgrade to a new version by pulling a new image and restarting:

1. Stop current container

   docker stop metabase
   
2. Pull new image

   docker pull metabase/metabase:v0.54.1
   

   Always use specific version tags instead of latest in production.

3. Start with new image

   docker run -d -p 3000:3000 \
     -e "MB_DB_TYPE=postgres" \
     -e "MB_DB_DBNAME=metabase" \
     -e "MB_DB_HOST=postgres-host" \
     -e "MB_DB_USER=username" \
     -e "MB_DB_PASS=password" \
     --name metabase \
     metabase/metabase:v0.54.1
   

Metabase will automatically run database migrations on startup.

Full upgrade guide

Read the complete upgrade documentation

Health checks

Add health checks to your container:

docker run -d -p 3000:3000 \
  --health-cmd='curl --fail http://localhost:3000/api/health || exit 1' \
  --health-interval=15s \
  --health-timeout=5s \
  --health-retries=5 \
  --name metabase metabase/metabase

Check health status:

docker inspect --format='{{.State.Health.Status}}' metabase

Troubleshooting

Container won’t start

1. Check logs: docker logs metabase
2. Verify database is accessible from container
3. Check port conflicts: lsof -i :3000
4. Ensure sufficient memory (at least 2GB recommended)

Can’t connect to database

• Use fully qualified hostnames, not localhost
• Verify network connectivity: docker exec metabase ping postgres-host
• Check database credentials
• Ensure database accepts connections from Docker network

Out of memory errors

Increase Docker memory limit or set Java heap size:

docker run -d -p 3000:3000 \
  -e "JAVA_OPTS=-Xmx2g" \
  --name metabase metabase/metabase

Permission errors with volumes

Fix ownership of mounted directories:

sudo chown -R $(id -u):$(id -g) ~/metabase-data

Or use MUID and MGID environment variables.

Best practices

1. Use specific version tags

   Always pin to specific versions in production:

   metabase/metabase:v0.54.1  # Good
   metabase/metabase:latest   # Avoid in production
   
2. Use a production database

   Never use H2 in production. Configure PostgreSQL or MySQL.

3. Configure resource limits

   Set memory and CPU limits for predictable performance:

   services:
     metabase:
       image: metabase/metabase:v0.54.1
       deploy:
         resources:
           limits:
             memory: 4G
             cpus: '2'
   
4. Use Docker secrets for credentials

   Keep passwords out of environment variables and version control.

5. Implement health checks

   Configure health checks for automatic restart and monitoring.

6. Set up log aggregation

   Forward logs to a centralized logging system for production monitoring.

Next steps

Configure database

Set up PostgreSQL or MySQL for production

Environment variables

Complete reference for all configuration options

Upgrading Metabase

Learn how to safely upgrade Docker deployments

Backing up

Implement backup procedures for your database