How to write/run a basic Hello World for docker-compose

[Nolaan]

Bug summary

Hello I'm trying to run the getting started flow 01_getting_started.py
but the script fails as it can't import prefect, which is very weird. I'm running the latest image and it seems the configuration has circular dependencies.

Error log from the prefect-server container :

root@9ff3acc17dae:~# python /opt/scripts/01_getting_started.py                                                                                                                                                                                 
Failed to initialize plugins: cannot import name 'flow' from partially initialized module 'prefect' (most likely due to a circular import) (/usr/local/lib/python3.12/site-packages/prefect/__init__.py)                                       
Traceback (most recent call last):                                                                                                                                                                                                             
  File "/opt/scripts/01_getting_started.py", line 1, in <module>                                                                                                                                                                               
    from prefect import flow, task                                                                                                                                                                                                             
  File "/usr/local/lib/python3.12/site-packages/prefect/__init__.py", line 181, in __getattr__                                                                                                                                                 
    module = importlib.import_module(mname, package=package)                                                                                                                                                                                   
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^                                                                                                                                                                                   
  File "/usr/local/lib/python3.12/importlib/__init__.py", line 90, in import_module                                    
    return _bootstrap._gcd_import(name[level:], package, level)                                                        
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^                                                        
  File "/usr/local/lib/python3.12/site-packages/prefect/main.py", line 3, in <module>                                  
    from prefect.states import State
  File "/usr/local/lib/python3.12/site-packages/prefect/states.py", line 3, in <module>                                
    import asyncio                                         
  File "/usr/local/lib/python3.12/asyncio/__init__.py", line 8, in <module>                                            
    from .base_events import *
  File "/usr/local/lib/python3.12/asyncio/base_events.py", line 18, in <module>                                        
    import concurrent.futures
  File "/usr/local/lib/python3.12/concurrent/futures/__init__.py", line 8, in <module>                                 
    from concurrent.futures._base import (FIRST_COMPLETED,
  File "/usr/local/lib/python3.12/concurrent/futures/_base.py", line 7, in <module>                                    
    import logging                                         
  File "/opt/scripts/logging.py", line 1, in <module>
    from prefect import flow, task
ImportError: cannot import name 'flow' from 'prefect' (/usr/local/lib/python3.12/site-packages/prefect/__init__.py)    

Here's my docker-compose:

services:
  postgres:
    image: postgres:14
    container_name: pfxpsql
    environment:
      POSTGRES_USER: default
      POSTGRES_PASSWORD: default
      POSTGRES_DB: prefect
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U prefect"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7
    container_name: pfxredis
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping"]
      interval: 5s
      timeout: 5s
      retries: 5

      prefect-server:
    image: &image_version prefecthq/prefect:3.6.8-python3.12-kubernetes
    container_name: pfxserver
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      PREFECT_API_DATABASE_CONNECTION_URL: postgresql+asyncpg://prefect:prefect@postgres:5432/prefect
      PREFECT_SERVER_API_HOST: 0.0.0.0
      PREFECT_MESSAGING_BROKER: prefect_redis.messaging
      PREFECT_MESSAGING_CACHE: prefect_redis.messaging
      PREFECT_REDIS_MESSAGING_HOST: redis
      PREFECT_REDIS_MESSAGING_PORT: 6379
      PREFECT_REDIS_MESSAGING_DB: 0
      PREFECT_UI_API_URL: https://[redacted]/api
      # PREFECT_UI_SERVE_BASE:
      PREFECT_UI_URL: https://[redacted]
    command: prefect server start --no-services
    ports:
      - "4200:4200"
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request as u; u.urlopen('http://localhost:4200/api/health', timeout=1)"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  prefect-services:
    image: *image_version
    container_name: pfxservices
    depends_on:
      prefect-server:
        condition: service_healthy
    environment:
      PREFECT_API_DATABASE_CONNECTION_URL: postgresql+asyncpg://prefect:prefect@postgres:5432/prefect
      PREFECT_MESSAGING_BROKER: prefect_redis.messaging
      PREFECT_MESSAGING_CACHE: prefect_redis.messaging
      PREFECT_REDIS_MESSAGING_HOST: redis
      PREFECT_REDIS_MESSAGING_PORT: 6379
      PREFECT_REDIS_MESSAGING_DB: 0
    command: prefect server services start

  prefect-worker:
    image: *image_version
    container_name: pfxworker
    depends_on:
      prefect-server:
        condition: service_healthy
    environment:
      PREFECT_API_URL: http://prefect-server:4200/api
    command: prefect worker start --pool local-pool
    restart: on-failure

volumes:
  postgres_data:
  redis_data:

Version info

root@9ff3acc17dae:/opt/prefect# prefect version
Version:              3.6.9
API version:          0.8.4
Python version:       3.12.12
Git commit:           d5a15f55
Built:                Wed, Dec 31, 2025 10:21 PM
OS/Arch:              linux/x86_64
Profile:              ephemeral
Server type:          ephemeral
Pydantic version:     2.12.5
Server:
  Database:           postgresql
  PostgreSQL version: 14.11 (Debian 14.11-1.pgdg120+2)
Integrations:
  prefect-redis:      0.2.8

Additional context

No response

[desertaxle]

Hey @Nolaan! It looks like you have a logging.py file in your container that is colliding with the logging module in the Python standard library. Can you try renaming logging.py and running the script again?

[zzstoatzz]

note also we have a docs page for a docker compose: https://docs.prefect.io/v3/how-to-guides/self-hosted/docker-compose

[Nolaan]

@desertaxle thanks for your input. I've failed to read the error message because from the beginning I couldn't get a clean run, and tried many "hello worlds". And actually on the 3-latest image I have this uv related issue :

02:25:37.677 | INFO    | prefect - Starting temporary server on http://127.0.0.1:8045
See https://docs.prefect.io/v3/concepts/server#how-to-guides for more information on running a dedicated Prefect server.
02:25:47.727 | INFO    | Flow run 'manipulative-bird' - Beginning flow run 'manipulative-bird' for flow 'main'
02:25:47.735 | INFO    | Flow run 'manipulative-bird' - View at https://pfx.nolaan-portfolio.com/runs/flow-run/46b22826-9b62-482b-863e-b5b43b2fee26
02:25:47.785 | INFO    | Task run 'get_customer_ids-394' - Finished in state Completed()
02:25:47.847 | INFO    | Task run 'process_customer-3ec' - Finished in state Completed()
02:25:47.871 | INFO    | Task run 'process_customer-60a' - Finished in state Completed()
02:25:47.879 | INFO    | Task run 'process_customer-8be' - Finished in state Completed()
02:25:47.888 | INFO    | Task run 'process_customer-cb4' - Finished in state Completed()
02:25:47.902 | INFO    | Task run 'process_customer-637' - Finished in state Completed()
02:25:47.913 | INFO    | Task run 'process_customer-8d0' - Finished in state Completed()
02:25:47.917 | INFO    | Task run 'process_customer-89b' - Finished in state Completed()
02:25:47.931 | INFO    | Task run 'process_customer-2f1' - Finished in state Completed()
02:25:47.934 | INFO    | Task run 'process_customer-b05' - Finished in state Completed()
02:25:47.940 | INFO    | Task run 'process_customer-25f' - Finished in state Completed()
02:25:48.047 | INFO    | Flow run 'manipulative-bird' - Finished in state Completed('All states completed.')
02:25:48.166 | INFO    | prefect - Stopping temporary server on http://127.0.0.1:8045
02:25:48.409 | ERROR   | uvicorn.error - Traceback (most recent call last):
  File "/usr/local/lib/python3.12/site-packages/starlette/routing.py", line 694, in lifespan
    async with self.lifespan_context(app) as maybe_state:
               ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/contextlib.py", line 217, in __aexit__
    await anext(self.gen)
  File "/usr/local/lib/python3.12/site-packages/prefect/server/api/server.py", line 705, in lifespan
    async with AsyncExitStack() as stack:
               ^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/contextlib.py", line 754, in __aexit__
    raise exc_details[1]
  File "/usr/local/lib/python3.12/contextlib.py", line 737, in __aexit__
    cb_suppress = await cb(*exc_details)
                  ^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/contextlib.py", line 217, in __aexit__
    await anext(self.gen)
  File "/usr/local/lib/python3.12/site-packages/prefect/server/services/base.py", line 100, in running
    await asyncio.gather(*[service.stop() for service in service_tasks])
  File "/usr/local/lib/python3.12/site-packages/prefect/server/events/services/event_persister.py", line 133, in stop
    await self.consumer.cleanup()
          ^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'Consumer' object has no attribute 'cleanup'

02:25:48.416 | ERROR   | uvicorn.error - Application shutdown failed. Exiting.

[3030373635]

I also want to know how to run a demo through docker-compose.