Instructions in the "Run a FastAPI app" speedrun differ from those in the repo's readme and neither of them work

[kellenmace]

Instructions in the "Run a FastAPI app" speedrun differ from those in the repo's readme and neither of them work. Details are below.

Title: Run a FastAPI app
Location: https://fly.io/docs/python/frameworks/fastapi/
Source: https://github.com/superfly/docs/blob/main/python/frameworks/fastapi.html.markerb

Attempt #1 using Speedrun instructions

The Speedrun instructions for setting up a basic FastAPI server instruct the reader to run these commands:

git clone [email protected]:fly-apps/hello-fastapi.git fastapi-app
cd fastapi-app
fly launch --generate-name

When I ran fly launch --generate-name, it errored out with this output:

Opening https://fly.io/cli/launch/796a6d777577336a767670766c6536666766696d787772673235326a69636761 ...

Waiting for launch data... Done
Created app 'dry-bush-1875' in organization 'personal'
Admin URL: https://fly.io/apps/dry-bush-1875
Hostname: dry-bush-1875.fly.dev
Run `fly tokens create deploy -x 999999h` to create a token and set it as the FLY_API_TOKEN secret in your GitHub repository settings
See https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
Wrote config file fly.toml
Validating /Users/kellen.mace/Downloads/fastapi-app/fly.toml
✓ Configuration is valid
==> Building image
==> Building image with Depot
--> build:  (​)
[+] Building 6.9s (13/15)                                                                           
 => [internal] load build definition from Dockerfile                                           0.1s
 => => transferring dockerfile: 380B                                                           0.1s
 => [internal] load metadata for docker.io/library/python:3.10-slim                            0.3s
 => [internal] load metadata for docker.io/library/python:3.10                                 0.3s
 => [internal] load .dockerignore                                                              0.1s
 => => transferring context: 82B                                                               0.1s
 => [builder 1/6] FROM docker.io/library/python:3.10@sha256:e70cd7b54564482c0dee8cd6d8e314450  0.0s
 => => resolve docker.io/library/python:3.10@sha256:e70cd7b54564482c0dee8cd6d8e314450aac59ea0  0.0s
 => [stage-1 1/4] FROM docker.io/library/python:3.10-slim@sha256:f680fc3f447366d9be2ae53dc7a6  0.0s
 => => resolve docker.io/library/python:3.10-slim@sha256:f680fc3f447366d9be2ae53dc7a6447fe9b3  0.0s
 => [internal] load build context                                                              0.2s
 => => transferring context: 105.53kB                                                          0.2s
 => CACHED [stage-1 2/4] WORKDIR /app                                                          0.0s
 => CACHED [builder 2/6] WORKDIR /app                                                          0.0s
 => CACHED [builder 3/6] RUN pip install poetry                                                0.0s
 => CACHED [builder 4/6] RUN poetry config virtualenvs.in-project true                         0.0s
 => CACHED [builder 5/6] COPY pyproject.toml poetry.lock ./                                    0.0s
 => ERROR [builder 6/6] RUN poetry install                                                     6.0s
------                                                                                              
 > [builder 6/6] RUN poetry install:                                                                
2.586 Creating virtualenv fastapi-app in /app/.venv                                                 
3.272 Installing dependencies from lock file                                                        
3.658                                                                                               
3.658 Package operations: 36 installs, 0 updates, 0 removals                                        
3.658 
3.659   - Installing mdurl (0.1.2)
3.718   - Installing exceptiongroup (1.2.1)
3.719   - Installing idna (3.7)
3.723   - Installing markdown-it-py (3.0.0)
3.724   - Installing pygments (2.18.0)
3.726   - Installing sniffio (1.3.1)
3.729   - Installing typing-extensions (4.12.2)
4.040   - Installing anyio (4.4.0)
4.046   - Installing certifi (2024.6.2)
4.046   - Installing click (8.1.7)
4.046   - Installing h11 (0.14.0)
4.046   - Installing rich (13.7.1)
4.047   - Installing shellingham (1.5.4)
4.223   - Installing annotated-types (0.7.0)
4.224   - Installing dnspython (2.6.1)
4.225   - Installing httpcore (1.0.5)
4.227   - Installing httptools (0.6.1)
4.228   - Installing markupsafe (2.1.5)
4.230   - Installing pydantic-core (2.18.4)
4.231   - Installing python-dotenv (1.0.1)
4.233   - Installing pyyaml (6.0.1)
4.234   - Installing typer (0.12.3)
4.237   - Installing uvloop (0.19.0)
4.246   - Installing watchfiles (0.22.0)
4.248   - Installing websockets (12.0)
5.200   - Installing email-validator (2.1.1)
5.200   - Installing fastapi-cli (0.0.4)
5.201   - Installing httpx (0.27.0)
5.206   - Installing jinja2 (3.1.4)
5.206   - Installing orjson (3.10.4)
5.207   - Installing pydantic (2.7.3)
5.210   - Installing python-multipart (0.0.9)
5.211   - Installing starlette (0.37.2)
5.214   - Installing ujson (5.10.0)
5.217   - Installing uvicorn (0.30.1)
5.540   - Installing fastapi (0.111.0)
5.574 
5.574 Installing the current project: fastapi-app (0.1.0)
5.576 
5.576 Error: The current project could not be installed: Readme path `/app/README.md` does not exist.
5.576 If you do not want to install the current project use --no-root.
5.576 If you want to use Poetry only for dependency management but not for packaging, you can disable package mode by setting package-mode = false in your pyproject.toml file.
5.576 If you did intend to install the current project, you may need to set `packages` in your pyproject.toml file.
5.576 
------
==> Building image
==> Building image with Depot
--> build:  (​)
[+] Building 5.5s (13/15)                                                                           
 => [internal] load build definition from Dockerfile                                           0.1s
 => => transferring dockerfile: 380B                                                           0.1s
 => [internal] load metadata for docker.io/library/python:3.10-slim                            0.1s
 => [internal] load metadata for docker.io/library/python:3.10                                 0.1s
 => [internal] load .dockerignore                                                              0.1s
 => => transferring context: 82B                                                               0.1s
 => [builder 1/6] FROM docker.io/library/python:3.10@sha256:e70cd7b54564482c0dee8cd6d8e314450  0.0s
 => => resolve docker.io/library/python:3.10@sha256:e70cd7b54564482c0dee8cd6d8e314450aac59ea0  0.0s
 => [internal] load build context                                                              0.1s
 => => transferring context: 328B                                                              0.1s
 => [stage-1 1/4] FROM docker.io/library/python:3.10-slim@sha256:f680fc3f447366d9be2ae53dc7a6  0.0s
 => => resolve docker.io/library/python:3.10-slim@sha256:f680fc3f447366d9be2ae53dc7a6447fe9b3  0.0s
 => CACHED [stage-1 2/4] WORKDIR /app                                                          0.0s
 => CACHED [builder 2/6] WORKDIR /app                                                          0.0s
 => CACHED [builder 3/6] RUN pip install poetry                                                0.0s
 => CACHED [builder 4/6] RUN poetry config virtualenvs.in-project true                         0.0s
 => CACHED [builder 5/6] COPY pyproject.toml poetry.lock ./                                    0.0s
 => ERROR [builder 6/6] RUN poetry install                                                     4.9s
------                                                                                              
 > [builder 6/6] RUN poetry install:                                                                
1.958 Creating virtualenv fastapi-app in /app/.venv                                                 
2.539 Installing dependencies from lock file                                                        
2.855                                                                                               
2.855 Package operations: 36 installs, 0 updates, 0 removals                                        
2.855 
2.856   - Installing mdurl (0.1.2)
2.903   - Installing exceptiongroup (1.2.1)
2.903   - Installing idna (3.7)
2.906   - Installing markdown-it-py (3.0.0)
2.908   - Installing pygments (2.18.0)
2.909   - Installing sniffio (1.3.1)
2.913   - Installing typing-extensions (4.12.2)
3.175   - Installing anyio (4.4.0)
3.175   - Installing certifi (2024.6.2)
3.176   - Installing click (8.1.7)
3.180   - Installing h11 (0.14.0)
3.181   - Installing rich (13.7.1)
3.182   - Installing shellingham (1.5.4)
3.359   - Installing annotated-types (0.7.0)
3.359   - Installing httpcore (1.0.5)
3.360   - Installing dnspython (2.6.1)
3.360   - Installing httptools (0.6.1)
3.363   - Installing markupsafe (2.1.5)
3.365   - Installing pydantic-core (2.18.4)
3.370   - Installing python-dotenv (1.0.1)
3.371   - Installing pyyaml (6.0.1)
3.372   - Installing typer (0.12.3)
3.376   - Installing uvloop (0.19.0)
3.376   - Installing watchfiles (0.22.0)
3.379   - Installing websockets (12.0)
4.093   - Installing email-validator (2.1.1)
4.093   - Installing fastapi-cli (0.0.4)
4.094   - Installing httpx (0.27.0)
4.095   - Installing jinja2 (3.1.4)
4.096   - Installing orjson (3.10.4)
4.100   - Installing pydantic (2.7.3)
4.100   - Installing python-multipart (0.0.9)
4.102   - Installing starlette (0.37.2)
4.108   - Installing ujson (5.10.0)
4.111   - Installing uvicorn (0.30.1)
4.406   - Installing fastapi (0.111.0)
4.446 
4.446 Installing the current project: fastapi-app (0.1.0)
4.447 
4.447 Error: The current project could not be installed: Readme path `/app/README.md` does not exist.
4.447 If you do not want to install the current project use --no-root.
4.447 If you want to use Poetry only for dependency management but not for packaging, you can disable package mode by setting package-mode = false in your pyproject.toml file.
4.447 If you did intend to install the current project, you may need to set `packages` in your pyproject.toml file.
4.447 
------
Error: failed to fetch an image or build from source: error building: failed to solve: process "/bin/sh -c poetry install" did not complete successfully: exit code: 1

Attempt #2 using readme instructions

I then noticed that the readme for the repo shows this command (albeit with no context whatsoever):

fly launch --from https://github.com/fly-apps/hello-fastapi --into <my-app> 

So I though I'd give that a try. I ran fly launch --from https://github.com/fly-apps/hello-fastapi --into fastapi-app. It failed with this error output:

Created app 'fastapi-app-crimson-feather-2138' in organization 'personal'
Admin URL: https://fly.io/apps/fastapi-app-crimson-feather-2138
Hostname: fastapi-app-crimson-feather-2138.fly.dev
Run `fly tokens create deploy -x 999999h` to create a token and set it as the FLY_API_TOKEN secret in your GitHub repository settings
See https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
Wrote config file fly.toml
Validating /Users/kellen.mace/Downloads/fastapi-app/fly.toml
✓ Configuration is valid
==> Building image
==> Building image with Depot
--> build:  (​)
[+] Building 6.4s (13/15)                                                                           
 => [internal] load build definition from Dockerfile                                           0.2s
 => => transferring dockerfile: 380B                                                           0.2s
 => [internal] load metadata for docker.io/library/python:3.10-slim                            0.3s
 => [internal] load metadata for docker.io/library/python:3.10                                 0.3s
 => [internal] load .dockerignore                                                              0.1s
 => => transferring context: 82B                                                               0.1s
 => [internal] load build context                                                              0.3s
 => => transferring context: 105.53kB                                                          0.3s
 => [stage-1 1/4] FROM docker.io/library/python:3.10-slim@sha256:f680fc3f447366d9be2ae53dc7a6  0.0s
 => => resolve docker.io/library/python:3.10-slim@sha256:f680fc3f447366d9be2ae53dc7a6447fe9b3  0.0s
 => [builder 1/6] FROM docker.io/library/python:3.10@sha256:e70cd7b54564482c0dee8cd6d8e314450  0.0s
 => => resolve docker.io/library/python:3.10@sha256:e70cd7b54564482c0dee8cd6d8e314450aac59ea0  0.0s
 => CACHED [stage-1 2/4] WORKDIR /app                                                          0.0s
 => CACHED [builder 2/6] WORKDIR /app                                                          0.0s
 => CACHED [builder 3/6] RUN pip install poetry                                                0.0s
 => CACHED [builder 4/6] RUN poetry config virtualenvs.in-project true                         0.0s
 => CACHED [builder 5/6] COPY pyproject.toml poetry.lock ./                                    0.0s
 => ERROR [builder 6/6] RUN poetry install                                                     5.4s
------                                                                                              
 > [builder 6/6] RUN poetry install:                                                                
2.412 Creating virtualenv fastapi-app in /app/.venv                                                 
3.074 Installing dependencies from lock file                                                        
3.396                                                                                               
3.396 Package operations: 36 installs, 0 updates, 0 removals                                        
3.396 
3.397   - Installing mdurl (0.1.2)
3.451   - Installing exceptiongroup (1.2.1)
3.451   - Installing idna (3.7)
3.454   - Installing markdown-it-py (3.0.0)
3.455   - Installing pygments (2.18.0)
3.458   - Installing sniffio (1.3.1)
3.460   - Installing typing-extensions (4.12.2)
3.732   - Installing anyio (4.4.0)
3.732   - Installing certifi (2024.6.2)
3.733   - Installing click (8.1.7)
3.735   - Installing h11 (0.14.0)
3.737   - Installing rich (13.7.1)
3.738   - Installing shellingham (1.5.4)
3.914   - Installing annotated-types (0.7.0)
3.915   - Installing dnspython (2.6.1)
3.915   - Installing httpcore (1.0.5)
3.916   - Installing httptools (0.6.1)
3.917   - Installing markupsafe (2.1.5)
3.920   - Installing pydantic-core (2.18.4)
3.921   - Installing python-dotenv (1.0.1)
3.921   - Installing pyyaml (6.0.1)
3.922   - Installing typer (0.12.3)
3.926   - Installing uvloop (0.19.0)
3.927   - Installing watchfiles (0.22.0)
3.931   - Installing websockets (12.0)
4.657   - Installing email-validator (2.1.1)
4.657   - Installing fastapi-cli (0.0.4)
4.658   - Installing httpx (0.27.0)
4.661   - Installing jinja2 (3.1.4)
4.662   - Installing orjson (3.10.4)
4.663   - Installing pydantic (2.7.3)
4.664   - Installing python-multipart (0.0.9)
4.665   - Installing starlette (0.37.2)
4.667   - Installing ujson (5.10.0)
4.668   - Installing uvicorn (0.30.1)
4.958   - Installing fastapi (0.111.0)
4.998 
4.998 Installing the current project: fastapi-app (0.1.0)
5.000 
5.000 Error: The current project could not be installed: Readme path `/app/README.md` does not exist.
5.000 If you do not want to install the current project use --no-root.
5.000 If you want to use Poetry only for dependency management but not for packaging, you can disable package mode by setting package-mode = false in your pyproject.toml file.
5.000 If you did intend to install the current project, you may need to set `packages` in your pyproject.toml file.
5.000 
------
==> Building image
==> Building image with Depot
--> build:  (​)
[+] Building 5.4s (13/15)                                                                           
 => [internal] load build definition from Dockerfile                                           0.1s
 => => transferring dockerfile: 380B                                                           0.1s
 => [internal] load metadata for docker.io/library/python:3.10-slim                            0.1s
 => [internal] load metadata for docker.io/library/python:3.10                                 0.2s
 => [internal] load .dockerignore                                                              0.1s
 => => transferring context: 82B                                                               0.1s
 => [builder 1/6] FROM docker.io/library/python:3.10@sha256:e70cd7b54564482c0dee8cd6d8e314450  0.0s
 => => resolve docker.io/library/python:3.10@sha256:e70cd7b54564482c0dee8cd6d8e314450aac59ea0  0.0s
 => [internal] load build context                                                              0.1s
 => => transferring context: 328B                                                              0.1s
 => [stage-1 1/4] FROM docker.io/library/python:3.10-slim@sha256:f680fc3f447366d9be2ae53dc7a6  0.0s
 => => resolve docker.io/library/python:3.10-slim@sha256:f680fc3f447366d9be2ae53dc7a6447fe9b3  0.0s
 => CACHED [stage-1 2/4] WORKDIR /app                                                          0.0s
 => CACHED [builder 2/6] WORKDIR /app                                                          0.0s
 => CACHED [builder 3/6] RUN pip install poetry                                                0.0s
 => CACHED [builder 4/6] RUN poetry config virtualenvs.in-project true                         0.0s
 => CACHED [builder 5/6] COPY pyproject.toml poetry.lock ./                                    0.0s
 => ERROR [builder 6/6] RUN poetry install                                                     4.8s
------                                                                                              
 > [builder 6/6] RUN poetry install:                                                                
1.913 Creating virtualenv fastapi-app in /app/.venv                                                 
2.451 Installing dependencies from lock file                                                        
2.739                                                                                               
2.739 Package operations: 36 installs, 0 updates, 0 removals                                        
2.739 
2.740   - Installing mdurl (0.1.2)
2.790   - Installing exceptiongroup (1.2.1)
2.790   - Installing idna (3.7)
2.793   - Installing markdown-it-py (3.0.0)
2.795   - Installing pygments (2.18.0)
2.798   - Installing sniffio (1.3.1)
2.802   - Installing typing-extensions (4.12.2)
3.075   - Installing anyio (4.4.0)
3.076   - Installing certifi (2024.6.2)
3.078   - Installing click (8.1.7)
3.079   - Installing h11 (0.14.0)
3.080   - Installing rich (13.7.1)
3.082   - Installing shellingham (1.5.4)
3.252   - Installing annotated-types (0.7.0)
3.252   - Installing dnspython (2.6.1)
3.253   - Installing httpcore (1.0.5)
3.255   - Installing httptools (0.6.1)
3.256   - Installing markupsafe (2.1.5)
3.257   - Installing pydantic-core (2.18.4)
3.259   - Installing python-dotenv (1.0.1)
3.264   - Installing pyyaml (6.0.1)
3.268   - Installing typer (0.12.3)
3.270   - Installing uvloop (0.19.0)
3.270   - Installing watchfiles (0.22.0)
3.275   - Installing websockets (12.0)
4.010   - Installing email-validator (2.1.1)
4.010   - Installing fastapi-cli (0.0.4)
4.011   - Installing httpx (0.27.0)
4.012   - Installing jinja2 (3.1.4)
4.014   - Installing orjson (3.10.4)
4.016   - Installing pydantic (2.7.3)
4.018   - Installing python-multipart (0.0.9)
4.020   - Installing starlette (0.37.2)
4.021   - Installing ujson (5.10.0)
4.024   - Installing uvicorn (0.30.1)
4.312   - Installing fastapi (0.111.0)
4.344 
4.344 Installing the current project: fastapi-app (0.1.0)
4.345 
4.345 Error: The current project could not be installed: Readme path `/app/README.md` does not exist.
4.345 If you do not want to install the current project use --no-root.
4.345 If you want to use Poetry only for dependency management but not for packaging, you can disable package mode by setting package-mode = false in your pyproject.toml file.
4.345 If you did intend to install the current project, you may need to set `packages` in your pyproject.toml file.
4.345 
------
Error: failed to fetch an image or build from source: error building: failed to solve: process "/bin/sh -c poetry install" did not complete successfully: exit code: 1

Summary

So since both the Speedrun instructions and repo readme instructions failed, I guess I have to to a bunch of manual debugging and try to figure out why "Readme path /app/README.md does not exist" and fix that issue.

Maybe running the launch command with --no-deploy first, then updating the COPY pyproject.toml poetry.lock ./ line in the Dockerfile to COPY pyproject.toml poetry.lock README.md ./ so that the readme file gets copied over, then finally deploying the app is the solution? Not sure what solution you'd recommend.

I feel like it shouldn't be this hard to get a simple "hello world" FastAPI server set up on Fly. The Speedrun instructions should "just work" and so should the fly launch 1-liner in the readme. Can you please fix those, or provide additional instructions to devs know what do to differently to get them to work on the first try? Thanks.