How to Deploy Metabase on Azure with an External PostgreSQL Database Using Docker

Recently, I had to self-host a Metabase instance and with my Azure for students subscription, I decided to deploy it on Azure. I ran into a lot of issues in the process and couldn't find a comprehensive article to walk me through it.

Using Blackbox AI, and a lot of google research and documentation reading, I was finally able to fix it. I decided to create this tutorial to help anyone looking to deploy Metabase on Azure with an external postgres DB.

Metabase is an open-source business intelligence tool that allows you to create charts, tables, and dashboards to analyze your data. It provides a user-friendly interface for querying databases and visualizing results.

A Metabase dashboard from metabase.com

This tutorial will walk you through the process of deploying Metabase on Azure with an external PostgreSQL database using Docker and an Azure Container Registry.

Prerequisites

Before we begin, make sure you have the following:

1. An existing PostgreSQL database on Azure or elsewhere.

2. Docker installed on your local machine

3. An Azure subscription and access to the Azure portal.

4. Basic knowledge of how to use Azure and Docker

Step 1: Create an Azure Container Registry (ACR)

Azure Container Registry (ACR) is a managed container registry service that allows you to store and manage your container images. Here's how to create one:

1. Log in to the Azure portal and search for the Container Registry service.

   

2. Click on "Create a container registry" and fill in the required details, such as registry name, resource group, and location. If you haven't created a resource group for your project, click on create new.

3. Click "Review + create" to create the ACR.

   

Step 2: Build a Docker image for Metabase

1. On your local machine, create a new directory for your Metabase project and navigate into it.

2. Create a Dockerfile with the following content:

FROM metabase/metabase:latest

ENV MB_DB_TYPE=postgres 
ENV MB_DB_HOST=<your-postgres-db-host> 
ENV MB_DB_PORT=5432 ENV 
MB_DB_DBNAME=<your-postgres-db-name> 
ENV MB_DB_USER=<your-postgres-db-username> 
ENV MB_DB_PASS=<your-postgres-db-password>

EXPOSE 3000

Replace the placeholders with your actual PostgreSQL database credentials and host. Note that using the correct credentials and host is crucial for the deployment to work.

3. Build the Docker image by running the command: docker build -t metabase-image .

Step 3: Push the Docker image to Azure Container Registry (ACR)

1. Log in to your ACR using the command: docker login <your-acr-name>.azurecr.io

   You can find the login details from Settings > Access Keys on the container registry page.

2. Tag the Docker image with the ACR URL: docker tag metabase-image <your-acr-name>.azurecr.io/metabase-image:latest

3. Push the image to ACR: docker push <your-acr-name>.azurecr.io/metabase-image:latest

4. Check the resource page activity logs to confirm that the image has been pushed.

Step 4: Create an Azure App Service

1. Navigate to the Azure App Service service in the Azure portal.

2. Click on "Create a web app" and fill in the required details, such as app name, resource group, and location. Use same resource group and location as your container registry.

   

3. Select "Container" to publish from and set your Linux plan (4GB min is preferred).

4. On the next page, select "Azure Container Registry" as the image source and choose the "Single Container".

5. Fill the registry options by selecting your registry, image name and tag "latest" from the drop-down menus. Leave the startup up command blank.

6. 

   Click on "Review + create" to create your web app.

Step 6: Start the App Service

1. After deployment is completed, navigate to the web app resource.

2. Check the logs in "Development Center" to see the status of your app. You should see something like if Metabase was deployed succesfully:

   

Troubleshooting

When deploying Metabase on Azure using Docker and Azure Container Registry, you may encounter some issues.

Use the Azure App Service logs to troubleshoot issues with the Metabase deployment. You can access the logs in the Azure portal or using the Azure CLI. Look for error messages and exceptions that may indicate the cause of the issue.

If you can't figure out where the issue is coming from, try running the container in interactive mode on your local machine:

docker run -it <registry-name>.azurecr.io/metabase-image:latest

Replace <registry_name> with the name of your Azure Container Registry. Check the logs to see what the problem could be.

Common Issues and Solutions

Error 1: Unable to connect to the PostgreSQL database

• Symptom: Metabase fails to start, and the logs show an error connecting to the PostgreSQL database.

• Solution: Verify that the PostgreSQL database credentials are correct, and that the database is reachable from the Azure App Service. Check the Azure App Service's network settings and ensure that the PostgreSQL database is allowed in the firewall rules.

Error 2: Metabase container fails to start

• Symptom: The Metabase container fails to start, and the Azure App Service logs show an error.

• Solution: Check the Metabase container logs for errors, and verify that the Docker image is correct and up-to-date. Ensure that the Azure App Service has sufficient resources (e.g., CPU, memory) to run the Metabase container.

Error 3: Azure App Service deployment fails

• Symptom: The Azure App Service deployment fails, and the logs show an error.

• Solution: Check the Azure App Service deployment logs for errors, and verify that the Azure App Service plan has sufficient resources (e.g., CPU, memory) to run the Metabase container. Ensure that the Azure Container Registry credentials are correct, and that the Metabase Docker image is available in the registry.

Error 4: Migration Lock Issue

• Symptom: Metabase fails to start, and the logs show an error related to a migration lock.

Solution: Check if there is a migration lock on the Metabase database. If so, follow these steps to release the locks and commit the changes to a new image:

![Update the web app service to use the new image](cdn.hashnode.com/res/hashnode/image/upload/.. align="center")

Conclusion

Congratulations! You have successfully deployed Metabase on Azure using Docker and Azure Container Registry. Metabase is now up and running, and you can access it through the Azure App Service URL: http://<your-app-service-name>.azurewebsites.net.

Setup your admin account and you're good to go! From here, you can customize Metabase to suit your needs, add additional features, and connect to your data sources.

Check the setup page to ensure that "Productionize" is checked. This shows that your Metabase instance was deployed with a production-ready db - the Postgres db you specified in the Dockerfile.

Additional Resources

For more information on Metabase, Azure, and Docker, check out the following resources:

• Metabase documentation: https://www.metabase.com/docs/

• Azure documentation: https://docs.microsoft.com/en-us/azure/

• Docker documentation: https://docs.docker.com/

• Azure Container Registry documentation: https://docs.microsoft.com/en-us/azure/container-registry/

• Metabase Forum: https://discourse.metabase.com/

If you're looking to deploy Metabase with an Azure database, here's a guide by Metabase to help.