How To Install Metabase on Debian 12

In this tutorial, we will show you how to install Metabase on CentOS Stream 10. Metabase stands out as one of the most powerful open-source business intelligence and analytics tools available today. Its intuitive interface allows anyone in your organization to work with data, create insightful dashboards, and make data-driven decisions without requiring extensive technical knowledge. Installing Metabase on Debian 12 provides a stable, secure foundation for your analytics infrastructure.

This comprehensive guide will walk you through the complete process of installing Metabase on Debian 12, from system preparation to final configuration. Whether you’re a system administrator looking to deploy Metabase for your organization or a data enthusiast wanting to explore this powerful tool, this guide covers everything you need to know to get Metabase up and running smoothly on your Debian system.

By following this step-by-step tutorial, you’ll learn how to properly configure Metabase as a system service, secure it with Nginx as a reverse proxy, and ensure it starts automatically on system boot. Let’s begin building your robust analytics platform with Metabase on Debian 12.

Table of Contents

Prerequisites

Before diving into the Metabase installation process, ensure your system meets the following requirements:

Hardware Requirements:

Minimum 2GB RAM (4GB or more recommended for production use)
At least 2 CPU cores (more cores will improve performance)
Minimum 10GB storage space (SSD recommended for better performance)
Stable network connection

Software Requirements:

Debian 12 (Bookworm) with root or sudo access
Java 11 or higher (Metabase is Java-based)
A database server for Metabase’s application database (PostgreSQL, MySQL, or MariaDB recommended for production)
Basic Linux command-line knowledge
Web server (Nginx) for reverse proxy setup (optional but recommended)

Network Configuration:

Accessible port 3000 (default Metabase port)
If using Nginx as a reverse proxy, port 80 (HTTP) and/or 443 (HTTPS) should be accessible
Firewall rules adjusted to allow necessary traffic

Having all prerequisites in place before beginning the installation will ensure a smooth deployment process and help avoid common pitfalls. The following sections will guide you through each step of the installation process in detail.

Step 1: Preparing Your Debian 12 System

The first step in installing Metabase is preparing your Debian 12 system with all necessary dependencies and configurations. This creates a solid foundation for a stable Metabase installation.

Updating System Packages

Always start by updating your system’s package index and upgrading existing packages:

sudo apt update
sudo apt upgrade -y

This ensures you’re working with the latest security patches and software versions available in the Debian repositories.

Installing Java

Since Metabase is a Java application, you need to install an appropriate Java version. Metabase requires Java 11 or higher:

sudo apt install -y default-jdk

Verify the Java installation and version:

java -version

You should see output similar to:

openjdk version "17.0.10" 2024-01-16
OpenJDK Runtime Environment (build 17.0.10+7-Debian-1deb12u1)
OpenJDK 64-Bit Server VM (build 17.0.10+7-Debian-1deb12u1, mixed mode, sharing)

The default JDK in Debian 12 is typically Java 17, which works perfectly with Metabase.

Setting JAVA_HOME Environment Variable

For proper functionality, it’s recommended to set the JAVA_HOME environment variable:

echo "export JAVA_HOME=$(readlink -f /usr/bin/java | sed 's:/bin/java::')" | sudo tee -a /etc/profile.d/java_home.sh
source /etc/profile.d/java_home.sh

Verify the JAVA_HOME setting:

echo $JAVA_HOME

Creating Directory Structure

Create a dedicated directory for Metabase:

sudo mkdir -p /opt/metabase

This directory will store the Metabase JAR file and any related configuration files. The `/opt` directory is conventionally used for optional software packages and provides a clean separation from system files.

Step 2: Installing and Configuring a Database Server

While Metabase includes an embedded H2 database for testing purposes, a production environment should use a more robust database solution. This section covers installing and configuring a database server for Metabase.

Choosing a Database

Metabase supports several database systems for its application database:

PostgreSQL (recommended for production)
MySQL/MariaDB
H2 (embedded, suitable for testing only)

We’ll use PostgreSQL for this guide, as it offers excellent performance, reliability, and is well-supported by both Debian and Metabase.

Installing PostgreSQL

Install PostgreSQL server and client packages:

sudo apt install -y postgresql postgresql-client

Verify the installation:

sudo systemctl status postgresql

Creating a Metabase Database and User

Connect to PostgreSQL as the postgres user:

sudo -u postgres psql

Create a dedicated database and user for Metabase:

CREATE DATABASE metabase;
CREATE USER metabaseuser WITH ENCRYPTED PASSWORD 'choose_a_strong_password';
GRANT ALL PRIVILEGES ON DATABASE metabase TO metabaseuser;
\q

Configuring PostgreSQL for Remote Connections (Optional)

If Metabase will run on a different server than your database, edit PostgreSQL’s configuration:

sudo nano /etc/postgresql/*/main/postgresql.conf

Uncomment and modify the `listen_addresses` line:

listen_addresses = '*'

Then edit the client authentication configuration:

sudo nano /etc/postgresql/*/main/pg_hba.conf

Add a line to allow connections from Metabase’s IP address:

host    metabase        metabaseuser    metabase_server_ip/32    md5

Restart PostgreSQL to apply changes:

sudo systemctl restart postgresql

These steps create a secure, dedicated database environment for your Metabase installation.

Step 3: Downloading and Installing Metabase

Now that the system is prepared and the database is configured, it’s time to download and install Metabase itself.

Downloading the Latest Metabase Release

First, check the latest Metabase version from the official website, then download the JAR file:

cd /tmp
wget https://downloads.metabase.com/latest/metabase.jar

Alternatively, if you need a specific version:

export VER=0.48.6  # Replace with your desired version
wget https://downloads.metabase.com/v${VER}/metabase.jar

Moving Metabase to the Installation Directory

Move the downloaded JAR file to the Metabase directory:

sudo mv metabase.jar /opt/metabase/

Verifying the JAR File Integrity

It’s good practice to verify the integrity of the downloaded file:

sha256sum /opt/metabase/metabase.jar

Compare this hash with the one provided on the Metabase downloads page to ensure the file hasn’t been tampered with.

Testing the JAR File

Before proceeding with service configuration, test if the JAR file can run correctly:

java -jar /opt/metabase/metabase.jar

If everything is working correctly, you should see Metabase startup logs. Press Ctrl+C to stop the process after confirming it works.

Step 4: Configuring Metabase Environment Variables

Proper configuration of environment variables is crucial for Metabase’s operation, especially for database connections and performance tuning.

Creating the Configuration File

Create a configuration file to store environment variables:

sudo nano /etc/default/metabase

Add the following variables, adjusting values to match your environment:

# Database connection settings
MB_DB_TYPE=postgres
MB_DB_DBNAME=metabase
MB_DB_PORT=5432
MB_DB_USER=metabaseuser
MB_DB_PASS=your_password_here
MB_DB_HOST=localhost

# Application settings
MB_JETTY_PORT=3000

# Java options (adjust memory according to your server capacity)
JAVA_OPTS="-XX:+HeapDumpOnOutOfMemoryError -Xmx2g"

This configuration specifies:

PostgreSQL as the application database
Connection details for the database
The port Metabase will run on (default is 3000)
Memory allocation for Java (2GB maximum heap size in this example)

Additional Configuration Options

You can also configure other settings like:

# Site URL (important for email notifications and correct link generation)
MB_SITE_URL=https://metabase.yourdomain.com

# Email settings
MB_EMAIL_SMTP_HOST=smtp.example.com
MB_EMAIL_SMTP_PORT=587
MB_EMAIL_SMTP_USER=your_email_user
MB_EMAIL_SMTP_PASSWORD=your_email_password
MB_EMAIL_FROM_ADDRESS=metabase@yourdomain.com

Customizing these settings will ensure Metabase operates optimally in your specific environment.

Step 5: Creating an Unprivileged User for Metabase

For security reasons, Metabase should run under a dedicated, unprivileged user account rather than as root. This section covers creating that user.

Creating the Metabase User and Group

Create a dedicated system group and user:

sudo groupadd -r metabase
sudo useradd -r -s /bin/false -g metabase metabase

The `-r` flag creates a system account, and `-s /bin/false` prevents direct login to the account.

Setting Proper Permissions

Set ownership of the Metabase directory and files to the new user:

sudo chown -R metabase:metabase /opt/metabase

Create and set permissions for the log file:

sudo touch /var/log/metabase.log
sudo chown metabase:metabase /var/log/metabase.log

Set appropriate permissions for the configuration file:

sudo chmod 640 /etc/default/metabase
sudo chown root:metabase /etc/default/metabase

These steps ensure that Metabase runs with minimal necessary privileges, adhering to security best practices.

Step 6: Setting Up Metabase as a Systemd Service

To ensure Metabase starts automatically at system boot and can be managed easily, set it up as a systemd service.

Creating the Systemd Service File

Create a service definition file:

sudo nano /etc/systemd/system/metabase.service

Add the following configuration:

[Unit]
Description=Metabase server
After=syslog.target
After=network.target
After=postgresql.service

[Service]
WorkingDirectory=/opt/metabase
ExecStart=/usr/bin/java --add-opens java.base/java.nio=ALL-UNNAMED -jar /opt/metabase/metabase.jar
EnvironmentFile=/etc/default/metabase
User=metabase
Type=simple
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=metabase
SuccessExitStatus=143
TimeoutStopSec=120
Restart=always

[Install]
WantedBy=multi-user.target

This configuration:

Ensures Metabase starts after network and database services
Runs Metabase as the dedicated metabase user
Uses the environment variables defined in the previous step
Automatically restarts Metabase if it crashes
Sends logs to syslog for easier monitoring

Configuring Syslog for Metabase

Create a syslog configuration file for Metabase:

sudo nano /etc/rsyslog.d/metabase.conf

Add the following line:

if $programname == 'metabase' then /var/log/metabase.log
& stop

Restart rsyslog to apply the changes:

sudo systemctl restart rsyslog

This configuration directs all Metabase logs to a dedicated log file.

Enabling and Starting the Metabase Service

Reload systemd to recognize the new service, then enable and start Metabase:

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

Check the service status to ensure it’s running correctly:

sudo systemctl status metabase.service

You should see “active (running)” if everything is working correctly.

Step 7: Securing Metabase with Nginx as a Reverse Proxy

While Metabase can run standalone, using Nginx as a reverse proxy provides additional security benefits, SSL termination, and potentially better performance.

Installing Nginx

Install Nginx web server:

sudo apt install -y nginx

Creating an Nginx Configuration File for Metabase

Create a new Nginx server block configuration:

sudo nano /etc/nginx/sites-available/metabase

Add the following configuration:

server {
    listen 80;
    server_name metabase.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        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;
    }
}

For enhanced security, configure SSL with Let’s Encrypt:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d metabase.yourdomain.com

This will modify your Nginx configuration to include SSL settings.

Enabling the Nginx Configuration

Create a symbolic link to enable the site:

sudo ln -s /etc/nginx/sites-available/metabase /etc/nginx/sites-enabled/

Test the configuration and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

Your Metabase instance should now be accessible securely via https://metabase.yourdomain.com.

Step 8: Launching and Initial Setup

With everything configured, it’s time to access Metabase and complete the initial setup.

Accessing the Web Interface

Open your browser and navigate to:

http://your-server-ip:3000 (if accessing directly)
https://metabase.yourdomain.com (if using Nginx with SSL)

Install Metabase on Debian 12

First-Time Setup Wizard

Follow the setup wizard to:

Create an administrator account
Connect to your data sources
Set up basic preferences
Optionally join the Metabase community

Verifying Complete Installation

Check that all components are working together:

Test database connections
Create a sample dashboard
Ensure email notifications work (if configured)

This final verification ensures your Metabase installation is fully functional and ready for use.

Troubleshooting Common Installation Issues

Even with careful planning, issues can arise during installation. Here are solutions to common problems:

Java-Related Issues

Problem: Incorrect Java version

Check your Java version with `java -version`
Ensure you’re using Java 11 or higher
Install the correct version if needed: `sudo apt install openjdk-11-jdk`

Problem: Memory allocation errors

Adjust the `-Xmx` parameter in `/etc/default/metabase`
For example, increase memory: `JAVA_OPTS=”-Xmx4g”`

Database Connection Problems

Problem: Cannot connect to database

Verify database credentials in `/etc/default/metabase`
Check PostgreSQL is running: `sudo systemctl status postgresql`
Ensure the database and user exist
Verify network connectivity and firewall settings

Problem: Permission denied errors

Check that the metabase user has necessary database privileges
Review PostgreSQL’s `pg_hba.conf` for correct client authentication settings

Service Startup Failures

Problem: Service fails to start

Check logs: `sudo journalctl -u metabase.service`
Verify file permissions: `ls -la /opt/metabase/`
Ensure the metabase user can read all necessary files

Problem: Port conflicts

Check if port 3000 is already in use: `sudo netstat -tuln | grep 3000`
Change the port in `/etc/default/metabase` if needed

Maintenance and Upgrading

Keeping your Metabase installation updated and properly maintained is crucial for security and performance.

Backing Up Metabase Data

Before any maintenance, back up your Metabase database:

sudo -u postgres pg_dump metabase > metabase_backup_$(date +%Y%m%d).sql

Also back up your configuration files:

sudo cp /etc/default/metabase /etc/default/metabase.bak
sudo cp /etc/systemd/system/metabase.service /etc/systemd/system/metabase.service.bak

Upgrading to a New Version

To upgrade Metabase:

Stop the Metabase service:
```
sudo systemctl stop metabase
```

Back up the current JAR file:

sudo cp /opt/metabase/metabase.jar /opt/metabase/metabase.jar.bak

Download the new version:

cd /tmp
wget https://downloads.metabase.com/latest/metabase.jar
sudo mv metabase.jar /opt/metabase/
sudo chown metabase:metabase /opt/metabase/metabase.jar

Start the service:
```
sudo systemctl start metabase
```
Verify the upgrade by checking the version in the admin interface.

Monitoring System Performance

Regularly monitor your Metabase instance:

Check logs: `sudo tail -f /var/log/metabase.log`
Monitor system resources: `htop` or `top`
Set up log rotation for Metabase logs

Database Maintenance

Periodically maintain your PostgreSQL database:

Run `VACUUM ANALYZE` to optimize performance
Monitor database size and plan for scaling if needed
Check for slow queries that might need optimization

Regular maintenance ensures your Metabase installation remains reliable and performant.

Congratulations! You have successfully installed Metabase. Thanks for using this tutorial for installing Metabase with Docker Compose on the Debian 12 “Bookworm” system. For additional help or useful information, we recommend you check the official Metabase website.

VPS Manage Service Offer

If you don’t have time to do all of this stuff, or if this is not your area of expertise, we offer a service to do “VPS Manage Service Offer”, starting from $10 (Paypal payment). Please contact us to get the best deal!