Initial FastAPI hello-world app with uv + Docker

Author: promominali

.dockerignore

@@ -0,0 +1,11 @@
+__pycache__
+*.pyc
+*.pyo
+.venv
+venv
+.env
+.git
+.gitignore
+.DS_Store
+.python-version
+.claude

.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Editor / tool state
+.claude/
+.DS_Store

.python-version

@@ -0,0 +1 @@
+3.13

Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.13-slim
+
+COPY --from=ghcr.io/astral-sh/uv:0.5.11 /uv /uvx /bin/
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PROJECT_ENVIRONMENT=/app/.venv \
+    PATH="/app/.venv/bin:$PATH" \
+    PORT=8080
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-install-project --no-dev
+
+COPY main.py ./
+
+EXPOSE 8080
+
+CMD exec uvicorn main:app --host 0.0.0.0 --port ${PORT}

README.md

@@ -0,0 +1,84 @@
+# fastapi-basic
+
+A minimal FastAPI "Hello, World!" service, managed with [uv](https://docs.astral.sh/uv/).
+
+This `main` branch contains only the app and local dev setup. Deployment is demonstrated on two separate branches:
+
+- **[`deploy-script`](../../tree/deploy-script)** — deploy with a local `gcloud` script ([deploy.sh](deploy.sh)).
+- **[`deploy-github`](../../tree/deploy-github)** — deploy from GitHub via a GitHub Actions workflow.
+
+## Stack
+
+- Python 3.13
+- FastAPI + Uvicorn (standard)
+- uv for dependency / venv management
+- Docker (python:3.13-slim + uv binary from `ghcr.io/astral-sh/uv`)
+
+## Project layout
+
+```
+.
+├── main.py             # FastAPI app (/, /healthz)
+├── pyproject.toml      # project metadata + deps
+├── uv.lock             # locked dependency graph
+├── .python-version     # pins Python 3.13 for uv
+├── Dockerfile          # uv-based container build
+└── .dockerignore
+```
+
+## Endpoints
+
+| Method | Path        | Response                       |
+| ------ | ----------- | ------------------------------ |
+| GET    | `/`         | `{"message": "Hello, World!"}` |
+| GET    | `/healthz`  | `{"status": "ok"}`             |
+| GET    | `/docs`     | Swagger UI                     |
+| GET    | `/redoc`    | ReDoc UI                       |
+
+## Prerequisites
+
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) (`brew install uv`)
+- Docker (only if you want to build/run the container locally)
+
+## Local development
+
+```bash
+uv sync
+uv run uvicorn main:app --reload --port 8080
+```
+
+Then:
+
+```bash
+curl http://localhost:8080/
+curl http://localhost:8080/healthz
+open http://localhost:8080/docs
+```
+
+### Managing dependencies
+
+```bash
+uv add <package>           # add a runtime dep
+uv add --dev <package>     # add a dev-only dep
+uv remove <package>        # remove a dep
+uv lock --upgrade          # refresh uv.lock
+```
+
+## Run with Docker
+
+```bash
+docker build -t fastapi-basic .
+docker run --rm -p 8080:8080 fastapi-basic
+```
+
+The image installs deps with `uv sync --frozen --no-dev` against `uv.lock`, so the container matches local exactly.
+
+## Deploying
+
+Check out one of the deploy branches:
+
+```bash
+git checkout deploy-script    # local gcloud-based deploy
+# or
+git checkout deploy-github    # GitHub Actions deploy
+```

main.py

@@ -0,0 +1,21 @@
+import os
+
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+def read_root():
+    return {"message": "Hello, World!"}
+
+
+@app.get("/healthz")
+def healthz():
+    return {"status": "ok"}
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "fastapi-basic"
+version = "0.1.0"
+description = "Add your description here"
+requires-python = ">=3.13"
+dependencies = [
+    "fastapi>=0.136.3",
+    "uvicorn[standard]>=0.49.0",
+]