Deploy Metabase with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it straightforward to run Metabase as a powerful business intelligence and analytics tool.

This guide walks you through deploying Metabase with a PostgreSQL database for its application data, persistent storage, and automatic HTTPS.

Prerequisites

• A VPS with at least 2 vCPUs, 2 GB RAM, and 10 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., bi.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  metabase:
    image: metabase/metabase:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - MB_DB_TYPE=postgres
      - MB_DB_DBNAME=metabase
      - MB_DB_PORT=5432
      - MB_DB_USER=metabase
      - MB_DB_PASS=${METABASE_DB_PASSWORD}
      - MB_DB_HOST=metabase-db
      - MB_SITE_URL=https://${METABASE_DOMAIN}
      - JAVA_TIMEZONE=${TZ:-UTC}
    depends_on:
      metabase-db:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3000/api/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5

  metabase-db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_DB=metabase
      - POSTGRES_USER=metabase
      - POSTGRES_PASSWORD=${METABASE_DB_PASSWORD}
    volumes:
      - ../files/metabase-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U metabase"]
      interval: 10s
      timeout: 5s
      retries: 5

Note: Metabase uses an application database (PostgreSQL here) to store its own configuration, questions, dashboards, and user data — this is separate from the data sources you'll query through Metabase. The default H2 database is not recommended for production.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
METABASE_DOMAIN	Your Metabase domain	bi.yourdomain.com
METABASE_DB_PASSWORD	PostgreSQL password for Metabase app database	a-strong-random-password
TZ	Server timezone for scheduled reports	America/New_York

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you. The MB_SITE_URL is important for email links and embedding to work correctly.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/metabase-db-data — PostgreSQL database files containing Metabase configuration, saved questions, dashboards, and user data

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths (e.g., /opt/metabase) because Dokploy may clean them during redeployment.

Metabase stores all its application data in PostgreSQL, so the database volume is the critical persistence layer. The Metabase container itself is stateless.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., bi.yourdomain.com)
3. Set the container port to 3000
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to the Metabase container.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — you should see both metabase and metabase-db containers start
3. Check the Logs tab for the metabase service. Look for: Metabase Initialization COMPLETE (first boot takes 1–3 minutes)
4. Open https://bi.yourdomain.com in your browser — you should see the Metabase setup wizard
5. Create your admin account, connect your first data source, and explore your data

Troubleshooting

Metabase takes a long time to start (first boot) Metabase runs database migrations on first startup, which can take 1–3 minutes. Watch the logs for progress. Subsequent restarts are much faster. Ensure the VPS has at least 2 GB RAM — Metabase is a Java application and needs sufficient heap space.

"Unable to connect to database" during setup This refers to your data source, not the Metabase application database. Ensure the data source is accessible from the Dokploy server. If connecting to another Docker service, use the Docker service name as the hostname. For external databases, ensure firewall rules allow the connection.

Scheduled reports and email not working Configure SMTP settings in Metabase's Admin > Settings > Email panel. Metabase needs outgoing SMTP access to send reports. Verify your VPS allows outbound connections on port 587/465.

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about Metabase in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running Metabase.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.