Metabase

Install Metabase from the App Store, create the admin account behind the setup lock, connect databases it can reach, back up its H2 file and update it safely.

Updated Oct 9, 2026 · 8 min read

Metabase is a business intelligence tool: you connect it to a database, then build questions, charts and dashboards that people without SQL skills can read and filter. Choose it when you want shared dashboards on your sales, orders or app data. This page covers installing Metabase from the App Store, the first-time setup, which databases it can connect to from a ZoPanel container, backups and updates.

Requirements

Important: Metabase cannot connect to MariaDB or PostgreSQL databases on the same server. Read Connecting databases first to make sure your data source is reachable.

Install Metabase

As an administrator

1. Open App Store. If you see Docker is required, click Install Docker first.

2. On the Metabase card, click Install.

3. Fill in the dialog:

   Field	What to enter
   Domain	The domain the app answers on, without http://. A new website is created for it.
   Owner	The hosting account the app belongs to. Its package limits apply to the container.
   Free SSL (Let's Encrypt)	Leave on. The certificate is issued at the end of the install if the domain points to the server.

4. Click Install and follow the task log until Metabase is available at http://<domain>.

5. If the log says SSL could not be issued yet, point the domain to the server and click Issue certificate on the website's SSL tab.

Metabase has no extra install fields. ZoPanel sets one variable, MB_DB_FILE=/metabase-data/metabase.db, so Metabase keeps its own data (users, questions, dashboards, connection settings) in an embedded H2 database file on the app's data volume.

As a customer

Customers install from App Store in their own panel when the package allows it; the quota line at the top shows how many apps and how much memory are left. Metabase needs 1536 MB of the package's RAM (MB) and one slot of Packages → Docker apps. See Packages and limits.

First-time setup

A new install is behind a setup lock: the first person to open Metabase becomes its administrator, so ZoPanel shows everyone else "This app is being set up" until you finish.

1. Open the website and go to the Docker tab. Wait until the status is running.
2. In the Setup lock is on card, click Open the app (only for me). Metabase opens in a new tab.
3. The first start takes one to two minutes. If the page says the site is busy or Metabase is initializing, wait; it reloads.
4. Click Let's get started.
5. Choose the language, then enter your name, email, company or team name and a password. Click Next. This first account is an administrator.
6. Answer What will you use Metabase for? (or pick Not sure yet).
7. Add a database now, or click I'll add my data later to explore with the Sample Database first.
8. Choose your usage data preference and finish with Take me to Metabase.
9. Back on the Docker tab, click Setup finished — open to everyone.

Essential settings

Open the grid icon at the top right and choose Admin:

• Settings → General → Site URL: make sure it is https://<your domain>. Links in emails and shared dashboards use it.
• Settings → Email: Metabase sends invitations, password resets and dashboard subscriptions by SMTP. A mailbox created in the panel works: SMTP host = your mail server name, port 587 (STARTTLS) or 465 (SSL), the full address and its password.
• People: invite colleagues and put them in groups.
• Permissions: decide which groups see which databases and whether they may write SQL.

Give Metabase a read-only database user for each data source: it only needs SELECT.

Connecting databases

Metabase runs in a container behind ZoPanel's container firewall:

What this means in practice:

• A database on the same server cannot be added, whatever host you type (localhost, 127.0.0.1, the server's public IP or a domain pointing to it). Turning on Remote access for the database does not change this: containers are blocked from the server's database ports.
• A database on another server works when that server accepts connections from this server's public IP. If the other server runs ZoPanel, open the database's Remote access, allow this server's public IP and use the Remote connection string it shows (see Databases).
• Managed databases (cloud MySQL or PostgreSQL services) work when they have a public endpoint and allow this server's IP. Endpoints on a private VPC address are not reachable.
• SSH tunnel in Metabase's connection form works to other servers, not to this one (port 22 of this server is blocked from containers).

To build dashboards on a shop or app database that lives on this server, the usual setup is to install Metabase on a second server and connect it through Remote access on this one.

To add a database: Admin → Databases → Add a database, choose the type (MySQL, MariaDB, PostgreSQL and others), fill in host, port, database name, user and password, then Save.

Where data lives and backups

The app's data is in /var/lib/zopanel-apps/<instance>/, where <instance> is the domain with dots replaced by hyphens (bi.example.com → bi-example-com). The container is zp-app-<instance>.

Your reporting data stays in the source databases; Metabase only stores queries and settings.

What ZoPanel backs up and what it does not: the Backups card on the website's Docker tab backs up the app's whole folder. Account backups and incremental backups cover website folders, databases and mailboxes of the account. They do not include /var/lib/zopanel-apps, so Metabase's dashboards and users are only in the app's own backups. The configuration backup (.zpb) holds the panel's record of the app, not its data.

To back up Metabase, click Back up now on the Backups card of the website's Docker tab. Administrators can also set a Schedule (Off, Every day or Every week; off by default) and how many copies to Keep (1–60, default 7), then click Save. Each backup archives /var/lib/zopanel-apps/<instance>/ into /var/backups/zopanel-apps/<instance>/YYYYMMDD-HHMMSS.tar.gz, a folder only root can read that does not count toward the account's disk quota. The container is paused (not stopped) for the few seconds of the copy, so the H2 file is copied in a consistent state, as after a power cut. Older copies beyond Keep are removed, and a failed scheduled backup sends administrators the Backup failed alert.

To restore, an administrator clicks Restore next to a backup. Metabase is stopped and its data replaced with the archive; the current data is kept aside until the restored app starts, and put back if it does not. Changes made since the backup are lost. Each backup also has a delete button (administrators only), and deleting the app together with its files deletes its backups too. Customers can click Back up now and see the list; the schedule and restores are done by the provider.

The archives stay on the same server. Copy important ones off it (for example with scp or rclone from /var/backups/zopanel-apps/<instance>/) and store them encrypted, since they contain the passwords of your saved database connections. To restore on another server, install Metabase on the same domain there, copy the archive into /var/backups/zopanel-apps/<instance>/ on the new server and click Restore on its Backups card.

Metabase recommends a production database (PostgreSQL or MySQL) instead of H2 for important installs. ZoPanel's Metabase uses H2 and the app database cannot be moved to a database on the same server, so keep regular backups (set a Schedule on the Backups card).

Update Metabase

1. Take a backup (Back up now on the Backups card). Metabase migrates its application database on start, and a downgrade is not supported.
2. On the Docker tab, click Update to latest (administrators only; customers ask their provider).
3. The task pulls the catalog image and recreates the container. Your data is kept. Metabase is unavailable for one to two minutes while it starts.

The catalog tag v0.63.x follows Metabase's 0.63 release line, so Update to latest brings the newest 0.63 patch. A move to a later Metabase line comes with a ZoPanel update.

Troubleshooting

Related

• App Store and S3 storage
• What each app does
• Databases
• Packages and limits
• Metabase documentation, Adding databases and Backing up Metabase