# 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.

Source: https://zopanel.net/docs/app-metabase  
Updated: 2026-10-09

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

| Item | Value |
| --- | --- |
| Image | `metabase/metabase:v0.63.x` |
| Memory limit | 1536 MB, 1 CPU |
| Free disk to install | About 2.6 GB on the Docker disk the first time (the image plus 1 GB kept free for the server) |
| Docker | Installed on the server (**App Store → Install Docker**) |
| Domain | A domain or subdomain whose A record points to the server, for example `bi.example.com` |
| Data source | A database Metabase can reach over the network; see [Connecting databases](#connecting-databases) before you install |

**Important:** Metabase cannot connect to MariaDB or PostgreSQL databases on the same server. Read [Connecting databases](#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](/docs/packages-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:

| Destination | Allowed? |
| --- | --- |
| Databases and APIs on other servers, on public addresses | Yes |
| Websites on this server through their public domain (80/443) | Yes |
| Mail on this server (25, 465, 587) | Yes |
| MariaDB, PostgreSQL, Redis or the panel **on this server** | **No** |
| Private networks (10.x, 172.16–31.x, 192.168.x, 100.64.x), loopback, cloud metadata | **No** |

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](/docs/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>`.

| Path on the server | Content |
| --- | --- |
| `/var/lib/zopanel-apps/<instance>/data/metabase.db.mv.db` | Metabase's H2 application database: users, questions, dashboards, saved connections |
| `/var/lib/zopanel-apps/<instance>/.env` | The container's variables (root only) |

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](/docs/updating).

## Troubleshooting

| Symptom or message | What to do |
| --- | --- |
| Visitors see "This app is being set up" | Click **Setup finished — open to everyone** on the **Docker** tab. |
| The page says the site is busy for a minute after install, update or restart | Metabase is still starting. Wait; the page reloads by itself. |
| Adding a database fails with a connection timeout or "connection refused" | The database is on this server or on a private network, or the remote server does not allow this server's IP. See [Connecting databases](#connecting-databases). |
| `not enough disk space: this app needs about 2.6 GB free and the server has … GB; free some space first` | Free disk space, then install again. |
| `Metabase needs 1536 MB of memory; your plan has … MB and your apps use … MB` | Raise the package's **RAM (MB)** or remove another app. |
| `the app did not start listening: …` | Read **Application output** on the **Docker** tab, then click **Restart**. |
| Metabase restarts or shows `OutOfMemoryError` in **Application output** | Heavy queries or many concurrent users exceeded 1536 MB. Limit large result sets, cache questions and avoid many dashboards refreshing at once. |
| Emails from Metabase are not delivered | Check **Admin → Settings → Email**; use port 587 or 465 with a real mailbox and test with **Send test email**. |

## Related

- [App Store and S3 storage](/docs/apps)
- [What each app does](/docs/app-catalog)
- [Databases](/docs/databases)
- [Packages and limits](/docs/packages-limits)
- [Metabase documentation](https://www.metabase.com/docs/latest/), [Adding databases](https://www.metabase.com/docs/latest/databases/connecting) and [Backing up Metabase](https://www.metabase.com/docs/latest/installation-and-operation/backing-up-metabase-application-data)