Serve flows in a long-lived Docker container

The .serve method allows you to easily elevate a flow to a deployment, listening for scheduled work to execute as a local process.

However, this “local” process does not need to be on your local machine. In this example we show how to run a flow in Docker container on your local machine, but you could use a Docker container on any machine that has Docker installed.

​

Overview

In this example, you will set up:

• a simple flow that retrieves the number of stars for some GitHub repositories
• a Dockerfile that packages up your flow code and dependencies into a container image

​

Writing the flow

Say we have a flow that retrieves the number of stars for a GitHub repository:

import httpx
from prefect import flow, task


@task(log_prints=True)
def get_stars_for_repo(repo: str) -> int:
    response = httpx.Client().get(f"https://api.github.com/repos/{repo}")
    stargazer_count = response.json()["stargazers_count"]
    print(f"{repo} has {stargazer_count} stars")
    return stargazer_count


@flow
def retrieve_github_stars(repos: list[str]) -> list[int]:
    return get_stars_for_repo.map(repos).wait()


if __name__ == "__main__":
    retrieve_github_stars.serve(
        parameters={
            "repos": ["python/cpython", "prefectHQ/prefect"],
        }
    )

We can serve this flow on our local machine using:

python serve_retrieve_github_stars.py

… but how can we package this up so we can run it on other machines?

​

Writing the Dockerfile

Assuming we have our Python requirements defined in a file:

prefect

and this directory structure:

├── Dockerfile
├── requirements.txt
└── serve_retrieve_github_stars.py

We can package up our flow into a Docker container using a Dockerfile.

​

Build and run the container

Now that we have a flow and a Dockerfile, we can build the image from the Dockerfile and run a container from this image.

​

Build (and push) the image

We can build the image with the docker build command and the -t flag to specify a name for the image.

docker build -t my-flow-image .

At this point, you may also want to push the image to a container registry such as Docker Hub or GitHub Container Registry. Please refer to each registry’s respective documentation for details on authentication and registry naming conventions.

​

Run the container

You’ll likely want to inject some environment variables into your container, so let’s define a .env file:

PREFECT_API_URL=<YOUR-API-URL>
PREFECT_API_KEY=<YOUR-API-KEY-IF-USING-PREFECT-CLOUD>

Then, run the container in detached mode (in other words, in the background):

docker run -d --env-file .env my-flow-image

​

Verify the container is running

docker ps | grep my-flow-image

You should see your container in the list of running containers, note the CONTAINER ID as we’ll need it to view logs.

​

View logs

docker logs <CONTAINER-ID>

You should see logs from your newly served process, with the link to your deployment in the UI.

​

Stop the container

docker stop <CONTAINER-ID>

​

Next steps

Congratulations! You have packaged and served a flow on a long-lived Docker container.

You may now easily deploy this container to other infrastructures, such as:

• Modal
• Google Cloud Run
• AWS Fargate / ECS
• Managed Kubernetes (For example: GKE, EKS, or AKS)

or anywhere else you can run a Docker container!