Deploy the Metabase Business Intelligence Platform to Koyeb
Tags: webdev, tutorial, programming, postgres
Published: 2023-07-21 09:24:29

## Introduction

[Metabase](https://www.metabase.com/) is an open-source business intelligence platform that can connect with many different data sources to offer insight into your organization's key functions. Metabase makes it possible to integrate all of your data into a single platform and offer data exploration tools to teams with varying levels of technical expertise. You can create dashboards to visualize changes, create models to simplify access to information, and run saved or ad hoc queries to find the data that matters most to you.

In this guide, we will show you how to set up a new Metabase instance on [Koyeb](https://www.koyeb.com/) in order begin gathering insights from your organization's data. Metabase provides a [Docker image](https://hub.docker.com/r/metabase/metabase) that we can use to get the platform up and running without needing to manage its Java runtime and dependencies directly. We will use [Neon](https://neon.tech/) to provision a PostgreSQL database where Metabase can store information about users, questions, dashboards, and more. Deploying with an external database allows Metabase to scale horizontally and redeploy seamlessly without losing data.

## Account requirements

To follow along with this guide, you will need to create accounts with the following services:

- **[Koyeb](https://app.koyeb.com/):** We will use Koyeb to deploy, run, and scale the Metabase application.
- **[Neon](https://www.koyeb.com/docs/integrations/databases/neon):** We will use Neon as our database provider. We will spin up a PostgreSQL database to store data like users, dashboards, and saved questions.

We will go over how to set up the resources we need from each of the above providers throughout the guide.

## Create a PostgreSQL database with Neon

Before we can deploy Metabase, we need to provision a database where it can store its data. Metabase can use a number of different backing databases, including a local [H2 database](https://www.h2database.com/html/main.html). Since we want our data to persist across deployments and be available from any number of application instances, we will opt for an external PostgreSQL database provisioned on [Neon](https://neon.tech/).

To create a new PostgreSQL database, log into your [Neon account](https://console.neon.tech/sign_in). In the Neon console, follow these steps to create a new PostgreSQL database:

1. Click the **Create a project** link.
2. On the next screen, choose a name for the new database. We'll use `metabase` for this guide.
3. Leave the version set at 15.
4. Select the region to deploy your database. In this guide, we will select "Europe (Frankfurt) to demonstrate deploying resources in Europe, but you should choose the region closest to your users.
5. Click the **Create project** button to begin provisioning your new database.

The following screen will show the connection details for your new database. Since Metabase is written in Java, in the drop-down menu, select **Java**. Copy the [JDBC](https://en.wikipedia.org/wiki/Java_Database_Connectivity) connection URI displayed so that we can use it later when we configure Metabase. It should look similar to this:

```
jdbc:postgresql://<NEON_HOST_PREFIX>.neon.tech/neondb?ssl=require&user=<NEON_USER>&password=<DB_PASSWORD>
```

## Deploy Metabase to Koyeb

Now we have the database connection URI, we can deploy Metabase to Koyeb.

Begin by logging into your [Koyeb account](https://app.koyeb.com/auth/signin). Follow these steps to deploy Metabase to the platform:

1. Click the **Create App** button on the [Koyeb console](https://app.koyeb.com/).
2. Select **Docker** as your deployment method.
3. Set the **Image** to `docker.io/metabase/metabase`. Leave the **Tag** blank to pull the latest image or select the [image tag](https://hub.docker.com/r/metabase/metabase/tags) you'd like to deploy.
4. In the **Instance** selection, click "Medium". Metabase recommends [allocating at least 1GB memory to Metabase](https://discourse.metabase.com/t/what-are-metabase-minimum-resources/21470/2) and [an additional 1-2GB of memory outside of Java](https://www.metabase.com/docs/latest/troubleshooting-guide/running.html#metabase-fails-to-start-due-to-heap-space-outofmemoryerrors).
5. Click **Advanced** to view additional settings.
6. Modify the `PORT` environment variable and the `Port` field of the **Expose your service** section to Metabase's default port: `3000`.
7. Click the **Add Variable** button to add two new variables. Create a variable called `MB_DB_CONNECTION_URI` and paste the JDBC connection URI you copied from Neon as the value. Next, add a variable called `JAVA_OPTS` with a value of `-Xmx1g` to set the Java heap size to 1GB of memory.
8. Set the **App name** to your choice.
9. Click the **Deploy** button.

Koyeb will pull the Metabase Docker image from Docker Hub and start a container based from it based on your configuration. The Metabase process will start up, connect to and initialize the database, and prepare for its first run.

## Start using Metabase

To access your new Metabase instance, visit your Koyeb Service's subdomain (you can find this on your Service's page). It will have the following format:

```
https://<YOUR_APP_NAME>-<KOYEB_ORG_NAME>.koyeb.app
```

You will be greeted by the Metabase setup page:

![Metabase default landing page](https://www.koyeb.com/static/images/tutorials/metabase/metabase_default_landing_page.png)

Click **Let's get started** to begin initial account creation process.

On the next page, select your preferred language:

![Metabase select language](https://www.koyeb.com/static/images/tutorials/metabase/language_selection.png)

Click **Next** to continue.

Fill out the information for your new user account:

![Metabase user account information](https://www.koyeb.com/static/images/tutorials/metabase/user_information.png)

Click **Next** to move on.

The next section let's you select what type of data you want to connect with Metabase and enter the associated connection details:

![Metabase connect data source](https://www.koyeb.com/static/images/tutorials/metabase/connect_data.png)

For now, just click **I'll add my data later** link to continue.

Select whether you want to send anonymous usage data back to Metabase:

![Metabase usage data](https://www.koyeb.com/static/images/tutorials/metabase/usage_data.png)

Make your selection and click **Finish** to wrap up.

Before you continue, you'll have the option to sign up for the Metabase newsletter:

![Metabase newsletter](https://www.koyeb.com/static/images/tutorials/metabase/subscribe_to_newsletter.png)

Click **Subscribe** if you'd like updates. Click **Take me to Metabase** to access your new Metabase instance.

You will be taken to Metabase's primary dashboard:

![Metabase dashboard](https://www.koyeb.com/static/images/tutorials/metabase/metabase_dashboard.png)

Click on any of the sample "x-rays" to view different examples of how to use Metabase as applied to the included sample database:

![Metabase sample x-ray](https://www.koyeb.com/static/images/tutorials/metabase/metabase_sample_x-ray.png)

To see the sample database itself, click **Browse data** under the **DATA** heading in the side navigation bar.

You can add additional data sources at any time by clicking the **Add your own data** item in the sidebar.

## Conclusion

In this guide, we covered how to deploy Metabase to Koyeb with their default Docker container. We used a PostgreSQL database provisioned through Neon to store the platform's information about users, views, questions, and other data. This configuration allows us to easily update the application and scale out as our requirements change.

As you add different data sources to your Metabase instance, check in with the application logs on the Deployment page in the [Koyeb control panel](https://app.koyeb.com/) to make sure everything is running smoothly. If you need additional resources, you can easily scale out your Deployment to better serve your users.