Skip to main content
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:
serve_retrieve_github_stars.py
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:
requirements.txt
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. 
# Use an official Python runtime as the base image
FROM python:3.12-slim

# Set the working directory in the container
WORKDIR /app

# Copy the requirements file into the container
COPY requirements.txt .

# Install the required packages
RUN pip install --no-cache-dir -r requirements.txt

# Copy the rest of the application code
COPY serve_retrieve_github_stars.py .

# Set the command to run your application
CMD ["python", "serve_retrieve_github_stars.py"]
Using pip, the image is built in about 20 seconds, and using uv, the image is built in about 3 seconds.You can learn more about using uv in the Astral documentation.

​
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:
.env
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: or anywhere else you can run a Docker container!