Running Prefect 2 with Docker Compose

If you’d like to run Prefect 2 using Docker Compose, I have created a sample repository that will help you get started. It contains a Docker Compose file and instructions that will help you run Prefect Orion, a Prefect agent, or the Prefect CLI. You can find it here:

If you have any questions or if there are any other examples you would like to see, please feel free to ask!


I was getting a “Can’t connect to Orion API at” error in the UI when trying this method. I could connect on the same machine/VM but the UI stopped working as soon as I tried to access it on another machine.

Had to do quite a lot of digging, and so for anyone with similar problems, the solution was to change the following lines in docker-compose.yml. The important bits is to start orion with the correct host prefect orion start --host and to set up the correct environment variables

  ### Prefect Orion API
    image: prefecthq/prefect:2.7.1-python3.11
    restart: always
      - prefect:/root/.prefect
    entrypoint: ["prefect", "orion", "start", "--host", ""]

Other links that helped:

Thanks for sharing this :raised_hands:

We appreciate you sharing this!

I’ll make some updates in the repo to cover this scenario. I’m also working on a follow-up that adds an Nginx container for serving requests to other machines.

1 Like

Hi Ryan

Thanks for sharing.

I am able to follow the instructions in the gitub. I run a Prefect Orion on remote VM, and deploy a flow from ‘docker compose run cli’ on the same VM.

But I can’t deploy from a different VM even after I set the PREFECT_API_URL. I got an error:
httpx.HTTPStatusError: Client error ‘422 Unprocessable Entity’ for url ‘
For more information check: 422 Unprocessable Entity - HTTP Status Code Glossary - WebFX

Do you have any suggestions?


The issue looks like to be caused by different prefect version used in remote and local VM. Works fine now.

Hi, qoolfly! Thanks for the update.

Do you know which versions you were running in each location?

1 Like