Document how to launch FastAPI in a container with explicit minor version, Poetry, and distroless nonroot runtime for Cloud Run (#223)

* Initial plan

* Implement FastAPI Docker improvements with Cloud Run support and PORT env var

Co-authored-by: davideme <[email protected]>

* Fix Dockerfile to use Poetry in build stage and distroless runtime

Co-authored-by: davideme <[email protected]>

* Use nonroot distroless image for improved security

Co-authored-by: davideme <[email protected]>

* Refactor launcher.py for style and consistency

Updated string quotes to double quotes, improved command formatting for readability, and standardized the main entry point check. Removed unused subprocess import.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: davideme <[email protected]>
Co-authored-by: Davide Mendolia <[email protected]>
Co-authored-by: Davide Mendolia <[email protected]>

Author: Copilot

src/python/Dockerfile

@@ -1,9 +1,12 @@
-FROM python:3.12 AS builder
+FROM python:3.12-slim AS build-env
+COPY . /app
+WORKDIR /app
 
-WORKDIR /usr/src/app
+# Install curl for Poetry installation
+RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
 
 # Install Poetry using the official installer
-RUN pip install --upgrade pip
+RUN pip install --no-cache-dir --upgrade pip
 RUN curl -sSL https://install.python-poetry.org | python3 -
 
 # Set PATH and configure Poetry
@@ -18,16 +21,13 @@ COPY pyproject.toml poetry.lock ./
 # Install production dependencies only
 RUN poetry install --only=main && rm -rf $POETRY_CACHE_DIR
 
-# Copy source code
-COPY . .
 
-
-FROM python:3.12 AS service
-WORKDIR /root/app
-
-# Copy the virtual environment and source code from builder stage
-COPY --from=builder /usr/src/app/.venv /root/app/.venv
-COPY --from=builder /usr/src/app /root/app
+FROM gcr.io/distroless/python3-debian12:nonroot
+COPY --from=build-env /app /app
+WORKDIR /app
 
 # Set environment to use the virtual environment
-ENV PATH="/root/app/.venv/bin:$PATH"
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Use Python launcher script to handle PORT env var for Cloud Run compatibility
+CMD ["python", "launcher.py"]

src/python/README.md

@@ -16,7 +16,7 @@ To run the server, please execute the following from the root directory:
 poetry install
 
 # Run the server
-poetry run uvicorn openapi_server.main:app --host 0.0.0.0 --port 8080
+poetry run fastapi run src/openapi_server/main.py --port 8080 --host 0.0.0.0
 ```
 
 and open your browser at `http://localhost:8080/docs/` to see the docs.
@@ -35,6 +35,56 @@ To run the server on a Docker container, please execute the following from the r
 docker-compose up --build
 ```
 
+### Docker Image Features
+
+The Docker image uses:
+- **Multi-stage build**: Build stage with Poetry dependency installation, production stage with Google's distroless Python image
+- **Poetry dependency management**: Uses Poetry in build stage for reproducible dependency installation
+- **Distroless runtime**: Production stage uses `gcr.io/distroless/python3-debian12:nonroot` for minimal attack surface and non-root execution
+- **Port Configuration**: Supports PORT environment variable for Cloud Run compatibility via launcher script
+- **FastAPI CLI**: Uses the modern `fastapi run` command for production deployment
+
+#### Building Docker Image
+
+```bash
+docker build -t lamp-control-api-python .
+```
+
+#### Running Docker Container
+
+```bash
+# Run with default port (80)
+docker run -p 8080:80 lamp-control-api-python
+
+# Run with custom port via environment variable (Cloud Run style)
+docker run -p 8080:8080 -e PORT=8080 lamp-control-api-python
+```
+
+## Cloud Run Deployment
+
+This application is optimized for Google Cloud Run deployment:
+
+### Environment Variables
+
+- `PORT` - The port for the HTTP server. Cloud Run automatically sets this variable for the ingress container. Defaults to 80 if not set.
+
+### Cloud Run Notes
+
+- The following environment variables are automatically added to all running containers except `PORT`. The `PORT` variable is only added to the ingress container.
+- The application will bind to `0.0.0.0:${PORT}` to accept traffic from Cloud Run's load balancer.
+- The Docker image uses a multi-stage build for optimal size and security.
+
+### Deployment Example
+
+```bash
+# Deploy to Cloud Run
+gcloud run deploy lamp-control-api \
+  --image gcr.io/YOUR_PROJECT/lamp-control-api-python \
+  --platform managed \
+  --region us-central1 \
+  --allow-unauthenticated
+```
+
 ## Tests
 
 To run the tests:

src/python/launcher.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""
+Launcher script for FastAPI application with Cloud Run PORT support.
+"""
+import os
+import sys
+
+
+def main():
+    port = os.environ.get("PORT", "80")
+
+    # Build the fastapi run command
+    cmd = [
+        sys.executable,
+        "-m",
+        "fastapi",
+        "run",
+        "src/openapi_server/main.py",
+        "--port",
+        port,
+        "--host",
+        "0.0.0.0",
+    ]
+
+    # Execute the command, replacing the current process
+    os.execv(sys.executable, cmd)
+
+
+if __name__ == "__main__":
+    main()