Deployment¶

We recommend Google Cloud Run or Hugging Face Spaces, which both have a free tier.

This section describes how to run your Mesop application using the following platforms:

Google Cloud Run
Google App Engine
Docker
Hugging Face Spaces

If you can run your Mesop app on Docker, you should be able to run it on many other cloud platforms, such as Hugging Face Spaces.

Example application¶

Let's start with an example application which will consist of the following files:

main.py
requirements.txt

main.py¶

This file contains your Mesop application code:

main.py

import mesop as me

@me.page(title="Home")
def home():
  me.text("Hello, world")

requirements.txt¶

This file specifies the Python dependencies needed. You may need to add additional dependencies depending on your use case.

requirements.txt

mesop
gunicorn

Cloud Run¶

We recommend using Google Cloud Run because it's easy to get started and there's a free tier.

Pre-requisites¶

You will need to create a Google Cloud account and install the gcloud CLI. See the official documentation for detailed instructions.

Procfile¶

Create Procfile to configure gunicorn to run Mesop.

Procfile

web: gunicorn --bind :8080 main:me

The --bind: 8080 will run Mesop on port 8080.

The main:me syntax is $(MODULE_NAME):$(VARIABLE_NAME): (see Gunicorn docs for more details):

Because the Mesop python file is main.py, the module name is main.
By convention, we do import mesop as me so the me refers to the main Mesop library module which is also a callable (e.g. a function) that conforms to WSGI.

Deploy to Google Cloud Run¶

In your terminal, go to the application directory, which has the files listed above.

Run the following command:

gcloud run deploy

Follow the instructions and then you should be able to access your deployed app.

Session Affinity¶

If you're running Mesop with MESOP_STATE_SESSION_BACKEND=memory, then you will want to enable session affinity in order to utilize the memory backend efficiently.

The command should be:

gcloud run services update $YOUR_SERVICE --session-affinity

By default gunicorn allocates one worker, but you should double check that gunicorn is configured correctly for the memory backend.

App Engine¶

This section describes deployment to Google App Engine using their flexible environments feature.

Pre-requisites¶

You will need to create a Google Cloud account and install the gcloud CLI. See the official documentation for detailed instructions.

You will also need to run:

gcloud app create --project=[YOUR_PROJECT_ID]
gcloud components install app-engine-python

app.yaml¶

Create app.yaml to configure App Engine to run Mesop.

app.yaml

runtime: python
env: flex
entrypoint: gunicorn -b :$PORT main:me

runtime_config:
  operating_system: ubuntu22
  runtime_version: "3.10"

manual_scaling:
  instances: 1

resources:
  cpu: 1
  memory_gb: 0.5
  disk_size_gb: 10

Deploy to App Engine¶

In your terminal, go to the application directory, which has the files listed above.

Run the following command:

gcloud app deploy

Follow the instructions and then you should be able to access your deployed app.

Docker¶

If you can run your Mesop app on Docker, you should be able to run it on many other cloud platforms.

Pre-requisites¶

Make sure Docker and Docker Compose are installed.

Dockerfile¶

Dockerfile

FROM python:3.10.14-bullseye

RUN apt-get update && \
  apt-get install -y \
  # General dependencies
  locales \
  locales-all && \
  # Clean local repository of package files since they won't be needed anymore.
  # Make sure this line is called after all apt-get update/install commands have
  # run.
  apt-get clean && \
  # Also delete the index files which we also don't need anymore.
  rm -rf /var/lib/apt/lists/*

ENV LC_ALL en_US.UTF-8
ENV LANG en_US.UTF-8
ENV LANGUAGE en_US.UTF-8

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Create non-root user
RUN groupadd -g 900 mesop && useradd -u 900 -s /bin/bash -g mesop mesop
USER mesop

# Add app code here
COPY . /srv/mesop-app
WORKDIR /srv/mesop-app

# Run Mesop through gunicorn. Should be available at localhost:8080
CMD ["gunicorn", "--bind", "0.0.0.0:8080", "main:me"]

docker-compose.yaml¶

docker-compose.yaml

services:
  mesop-app:
    build: .
    ports:
      - "8080:8080"

Run Docker image¶

In your terminal, go to the application directory, which has the files listed above.

Run the following command:

docker-compose up -d

Alternatively, if you do not want to use Docker Compose, you can run:

docker build -t mesop-app . && docker run -d -p 8080:8080 mesop-app

You should now be able to view your Mesop app at http://localhost:8080.

Hugging Face Spaces¶

Hugging Face Spaces has a free tier that gives you 2 vCPU and 16GB RAM, which is plenty for running Mesop applications that leverage generative AI APIs.

Pre-requisites¶

This section assumes you already have a free Hugging Face Space account.

Create new Space¶

Go to https://huggingface.co/spaces and click Create new Space.

Create new Hugging Face Space

Name your app and use Docker SDK¶

Name the Space mesop-hello-world you want and select the apache-2.0 license.

Next select the Docker SDK with a blank template.

Select Docker

CPU Basic and Create Space¶

Next make sure that you are using the free CPU Basic plan. Then click Create Space.

Create Hugging Face Space

Clone your Hugging Face Space Git Repository¶

Example command using Git over SSH:

git clone git@hf.co:spaces/<user-name>/mesop-hello-world
cd mesop-hello-world

Note: You'll need to have an SSH key configured on Hugging Face. See https://huggingface.co/docs/hub/en/security-git-ssh.

Create main.py¶

This is the same main.py file shown earlier, except we need to allow Hugging Face to iframe our Mesop app.

main.py

import mesop as me

@me.page(
  title="Home",
  security_policy=me.SecurityPolicy(
    allowed_iframe_parents=["https://huggingface.co"]
  ),
)
def home():
  me.text("Hello, world")

Create requirements.txt¶

This file is the same as the generic Docker setup:

requirements.txt

mesop
gunicorn

Create Dockerfile¶

This file is the same as the generic Docker setup:

Dockerfile

FROM python:3.10.14-bullseye

RUN apt-get update && \
  apt-get install -y \
  # General dependencies
  locales \
  locales-all && \
  # Clean local repository of package files since they won't be needed anymore.
  # Make sure this line is called after all apt-get update/install commands have
  # run.
  apt-get clean && \
  # Also delete the index files which we also don't need anymore.
  rm -rf /var/lib/apt/lists/*

ENV LC_ALL en_US.UTF-8
ENV LANG en_US.UTF-8
ENV LANGUAGE en_US.UTF-8

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Create non-root user
RUN groupadd -g 900 mesop && useradd -u 900 -s /bin/bash -g mesop mesop
USER mesop

# Add app code here
COPY . /srv/mesop-app
WORKDIR /srv/mesop-app

# Run Mesop through gunicorn. Should be available at localhost:8080
CMD ["gunicorn", "--bind", "0.0.0.0:8080", "main:me"]

Add app_port in README.md¶

Next we will need to open port 8080 which we specified in the Dockerfile. This is done through a config section in the README.md.

README.md

---
title: Mesop Hello World
emoji: 🐠
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: apache-2.0
app_port: 8080
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

Deploy to Hugging Face Spaces¶

The commands to commit your changes and push to the Hugging Face Spaces git repository are:

git add -A
git commit -m "Add hello world Mesop app"
git push origin main

View deployed app¶

Congratulations! You should now be able to view your app on Hugging Face Spaces.

The URL should be something like this:

https://huggingface.co/spaces/<user-name>/mesop-hello-world

Your deployed Hugging Face Spaces app