You’re ready to share your dashboard with Vizro it with your team? Perfect timing! In this guide, I’ll walk you through deploying a Vizro application with enterprise-grade features like custom domain support and password protection. Don’t worry - it’s easier than you might think.

What We’ll Cover

  • Setting up a production-ready Vizro application
  • Containerizing your dashboard with Docker
  • Deploying to Ploomber Cloud
  • Configuring custom domain access
  • Adding password protection for security

Project Structure

When deploying a Vizro application, you’ll need two essential files with specific names:

my-vizro-app/
├── ...              # All other files and folders
├── app.py           # To start your main application
└── requirements.txt # Python dependencies

Any additional Python files your dashboard needs can be organized in the same directory.

Setting Up Your Application

1. The Main Application (app.py)

If you’ve been developing with Vizro, you might have noticed a warning when running python app.py about not using the development server in production. Here’s how to properly structure your app.py for production deployment:

import vizro as vm
from vizro import Vizro

# Initialize your dashboard
# Replace this with your actual dashboard configuration
dashboard = vm.Dashboard(pages=[
    # Your pages configuration here
])

# Create the application instance
app = Vizro().build(dashboard)

# IMPORTANT: Expose the Flask server for production WSGI servers
# This is what Gunicorn will use to serve your application
server = app.dash.server

# Keep the development server for local testing
if __name__ == "__main__":
    app.run()

The key addition here is server = app.dash.server. This line exposes the underlying Flask server, allowing production WSGI servers like Gunicorn to properly handle your application.

2. Dependencies (requirements.txt)

The requirements.txt file lists all Python packages your application needs. While you can create it manually:

vizro==1.0.0
pandas==2.0.0
# Add other dependencies...

It’s better to automatically export your current environment’s dependencies. Open your terminal and use one of these commands:

# If using pip/venv
pip freeze > requirements.txt

# If using conda
conda list --export > requirements.txt

3. Containerizing Your Application

Now let’s package our application into a Docker container. Create a new file named Dockerfile in your project directory. Here’s a production-ready configuration with detailed explanations of each step:

# Use Python 3.11 slim image as our base
# The slim version keeps our container small while including essential packages
FROM python:3.11-slim

# Set the working directory in the container
# This is where our app will live inside the container
WORKDIR /app

# Copy and install dependencies first
# This step is separated to leverage Docker's cache layer
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt gunicorn vizro

# Copy all application files
# We do this after installing dependencies to speed up rebuilds
COPY . .

# Tell Docker that our app will use port 80
EXPOSE 80

# Start the application with Gunicorn
# Breaking down the command:
# - gunicorn: production-grade WSGI server
# - app:server: references the 'server' variable in our app.py
# - --bind 0.0.0.0:80: makes the app accessible from outside the container
ENTRYPOINT ["gunicorn", "app:server", "run", "--bind", "0.0.0.0:80"]

Why This Configuration Works

  1. Base Image: We use python:3.11-slim because:

    • It’s officially maintained
    • The slim variant reduces container size
    • Python 3.11 offers good performance, (any python version can be specify)

  2. Dependency Installation:

    • We install dependencies from your requirements.txt file
    • We also install gunicorn, which is necessary for production deployment

  3. Production Server:

    • Gunicorn is a production-grade WSGI server
    • It handles multiple workers and concurrent requests
    • Much more robust than Flask’s development server

Local Testing (Optional)

If you have Docker installed on your machine, it’s a good idea to test your application locally before deployment. This step helps catch any configuration issues early, but you can skip it if you don’t have Docker installed or prefer to deploy directly.

# Build your Docker image
docker build . -t vizro-app

# Run it locally
docker run -p 5000:80 vizro-app

Visit http://localhost:5000 in your browser to see your dashboard running in a container. This mirrors how it will run in production, giving you confidence that everything is properly configured.

Don’t have Docker? No worries! You can proceed directly to the deployment steps.

Deploying Your Vizro Dashboard

1. Prepare Your Package

Create a ZIP file containing your project folder. Make sure to include:

  • app.py - Your main application file
  • requirements.txt - Your dependencies
  • Any additional files your dashboard needs (data files, assets, etc.)

2. Deploy to Ploomber Cloud

  1. Log in to your Ploomber Cloud account
  2. Click the New button in the dashboard
  3. Select “Docker deployment” as your deployment option
  4. Upload your ZIP file containing the project

Upload your Zip

3. Configure Security (Optional)

In the Advanced Options section, you can set up authentication:

  • Basic Password Protection: Add a simple password to protect your dashboard Set up password protection
  • Enterprise Authentication: For Teams and Enterprise users, we offer:

4. Launch Your Dashboard

Click the Create button to deploy your Vizro application. Ploomber Cloud will:

  1. Build your container
  2. Deploy your application
  3. Provide you with a unique URL

Troubleshooting Guide

Common Issues and Solutions

  • Missing Files: Ensure your ZIP includes all necessary files
    my-vizro-app.zip
├── app.py           # Required
├── requirements.txt # Required
├── Dockerfile       # Required
└── [other files]    # As needed
  • Dependency Errors: Check your requirements.txt for:
    • Correct package versions
    • No conflicting dependencies
    • All required packages listed

Others Issues

  • Build Failures: Check the build logs in Ploomber Cloud
  • Application Crashes:
    • Review application logs in Ploomber Cloud dashboard
    • Verify environment variables if used

Getting Help

  1. Check the Vizro documentation
  2. Visit our community forum
  3. Contact our support team for:
    • Build issues
    • Authentication setup
    • Custom domain configuration

Adding a Custom Domain

Want to use your own domain for your Vizro dashboard? The process is straightforward and follows the same steps as setting up any custom domain on Ploomber Cloud. Check out our guide: How to Set Up a Custom Domain for Your App.

Next Steps

Your Vizro dashboard is now live! Here’s how you can take it to the next level:

Advanced Deployment Options:

For a quick start, we have a Vizro template repository that includes a working example with all the configurations we’ve covered in this guide.