Database backup

Dockerfile

@@ -77,6 +77,9 @@ RUN chown -R appuser:appuser /app/tmp_data
 # Set frontend path for FastAPI
 ENV FRONTEND_PATH=/app/frontend/dist
 
+# Set HF_HUB_DISABLE_EXPERIMENTAL_WARNING to avoid warnings
+ENV HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1
+
 # Switch to non-root user
 USER appuser
 

README.md

@@ -21,6 +21,10 @@ Spaces are very well suited to vibe-code demos using Cursor, Lovable, Claude Cod
 
 The backend (Python + FastAPI) and the frontend (TS + React + Tailwind) are located respectively in the `backend/` and `frontend/` folder.
 
+### Prerequisite
+
+To run this app locally, you MUST have `HF_TOKEN` set as environment variable with a valid token. You can generate a new one from your [user settings](https://huggingface.co/settings/tokens). This token is necessary to fake the OAuth workflow. If you click on "Sign in with Huggingface" in your dev environment, you will be authenticated as yourself and your local `HF_TOKEN` will be used. This is a mock to allow local testing while avoiding more complex configuration.
+
 ### Backend
 
 To run the backend, you'll need `uv` and Python3.12 installed.
@@ -67,8 +71,8 @@ Configuration should be automatically done if you clone the on the Hugging Face
 If you want to run it on your own, you can use Docker:
 
 ```bash
-docker build -t fastapi-react-space .
-docker run -e HF_TOKEN -p 9481:9481 fastapi-react-space
+make docker-build
+make docker-run
 ```
 
-Note that when running in Docker, the app runs in production mode without hot-reloading.
+When running in Docker, the app runs in production mode without hot-reloading.

backend/Makefile

@@ -1,7 +1,7 @@
 .PHONY: quality style
 
 dev:
-	uv run uvicorn src.app:app --reload
+	HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1 uv run uvicorn src.app:app --reload
 
 quality:
 	ruff check src
@@ -13,4 +13,4 @@ style:
 	ruff check --fix src
 
 preview:
-	FRONTEND_PATH=../frontend/dist/ uv run uvicorn src.app:app
+	HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1 FRONTEND_PATH=../frontend/dist/ uv run uvicorn src.app:app

backend/src/app.py

@@ -1,79 +1,10 @@
-from contextlib import asynccontextmanager
-
-from fastapi import Depends, FastAPI, HTTPException, Request
-from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import FileResponse, RedirectResponse
-from fastapi.staticfiles import StaticFiles
-from huggingface_hub import OAuthInfo, attach_huggingface_oauth, parse_huggingface_oauth
 from sqlmodel import select
 
-from . import constants
-from .database import get_session, init_db
+from .app_factory import OptionalOAuth, RequiredOAuth, create_app, get_session
 from .schemas import UserCount
 
-
-# Initialize database on startup
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    init_db()
-    yield
-
-
-# FastAPI app
-app = FastAPI(lifespan=lifespan)
-
-
-# Set CORS headers
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=[
-        # Can't use "*" because frontend doesn't like it with "credentials: true"
-        "http://localhost:5173",
-        "http://0.0.0.0:9481",
-        "http://localhost:9481",
-        "http://127.0.0.1:9481",
-    ],
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-# Mount frontend from dist directory (if configured)
-if constants.SERVE_FRONTEND:
-    # Production => Serve frontend from dist directory
-    app.mount(
-        "/assets",
-        StaticFiles(directory=constants.FRONTEND_ASSETS_PATH),
-        name="assets",
-    )
-
-    @app.get("/")
-    async def serve_frontend():
-        return FileResponse(constants.FRONTEND_INDEX_PATH)
-
-else:
-    # Development => Redirect to dev frontend
-    @app.get("/")
-    async def redirect_to_frontend():
-        return RedirectResponse("http://localhost:5173/")
-
-
-# Set up Hugging Face OAuth
-# To get OAuthInfo in an endpoint
-attach_huggingface_oauth(app)
-
-
-async def oauth_info_optional(request: Request) -> OAuthInfo | None:
-    return parse_huggingface_oauth(request)
-
-
-async def oauth_info_required(request: Request) -> OAuthInfo:
-    oauth_info = parse_huggingface_oauth(request)
-    if oauth_info is None:
-        raise HTTPException(
-            status_code=401, detail="Unauthorized. Please Sign in with Hugging Face."
-        )
-    return oauth_info
+# Configure FastAPI app + database
+app = create_app()
 
 
 # Health check endpoint
@@ -85,7 +16,7 @@ async def health():
 
 # User endpoints
 @app.get("/api/user")
-async def get_user(oauth_info: OAuthInfo | None = Depends(oauth_info_optional)):
+async def get_user(oauth_info: OptionalOAuth):
     """Get user information."""
     return {
         "connected": oauth_info is not None,
@@ -94,9 +25,7 @@ async def get_user(oauth_info: OAuthInfo | None = Depends(oauth_info_optional)):
 
 
 @app.get("/api/user/count")
-async def get_user_count(
-    oauth_info: OAuthInfo = Depends(oauth_info_required),
-) -> UserCount:
+async def get_user_count(oauth_info: RequiredOAuth) -> UserCount:
     """Get user count."""
     with get_session() as session:
         statement = select(UserCount).where(UserCount.name == oauth_info.user_info.name)
@@ -107,9 +36,7 @@ async def get_user_count(
 
 
 @app.post("/api/user/count/increment")
-async def increment_user_count(
-    oauth_info: OAuthInfo = Depends(oauth_info_required),
-) -> UserCount:
+async def increment_user_count(oauth_info: RequiredOAuth) -> UserCount:
     """Increment user count."""
     with get_session() as session:
         statement = select(UserCount).where(UserCount.name == oauth_info.user_info.name)

backend/src/app_factory.py

@@ -0,0 +1,158 @@
+import os
+from contextlib import asynccontextmanager, contextmanager
+from typing import Annotated, Generator
+
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, RedirectResponse
+from fastapi.staticfiles import StaticFiles
+from huggingface_hub import OAuthInfo, attach_huggingface_oauth, parse_huggingface_oauth
+from sqlalchemy.engine import Engine
+from sqlmodel import Session, SQLModel, create_engine
+
+from . import constants
+
+_ENGINE_SINGLETON: Engine | None = None
+
+# OAuth utilities
+
+
+async def _oauth_info_optional(request: Request) -> OAuthInfo | None:
+    return parse_huggingface_oauth(request)
+
+
+async def _oauth_info_required(request: Request) -> OAuthInfo:
+    oauth_info = parse_huggingface_oauth(request)
+    if oauth_info is None:
+        raise HTTPException(
+            status_code=401, detail="Unauthorized. Please Sign in with Hugging Face."
+        )
+    return oauth_info
+
+
+OptionalOAuth = Annotated[OAuthInfo | None, Depends(_oauth_info_optional)]
+RequiredOAuth = Annotated[OAuthInfo, Depends(_oauth_info_required)]
+
+
+# Database utilities
+def _get_engine() -> Engine:
+    """Get the engine."""
+    global _ENGINE_SINGLETON
+    if _ENGINE_SINGLETON is None:
+        _ENGINE_SINGLETON = create_engine(constants.DATABASE_URL)
+    return _ENGINE_SINGLETON
+
+
+@contextmanager
+def get_session() -> Generator[Session, None, None]:
+    """Get a session from the engine."""
+    engine = _get_engine()
+    with Session(engine) as session:
+        yield session
+
+
+@asynccontextmanager
+async def _database_lifespan(app: FastAPI):
+    """Handle database lifespan.
+
+    1. If backup is enabled enabled,
+       a. Try to load backup from remote dataset. If it fails, delete local database for a fresh start.
+       b. Start back-up scheduler.
+    2. If disabled, create local database file or reuse existing one.
+    3. Initialize database.
+    4. Yield control to FastAPI app.
+    5. Close database + force push backup to remote dataset.
+    """
+    if constants.BACKUP_DB:
+        from huggingface_hub import CommitScheduler, hf_hub_download
+
+        print("Back-up database is enabled")
+
+        # Try to load backup from remote dataset
+        print("Trying to load backup from remote dataset...")
+        try:
+            hf_hub_download(
+                repo_id=constants.BACKUP_DATASET_ID,  # type: ignore[arg-type]
+                repo_type="dataset",
+                filename="database.db",
+                token=constants.HF_TOKEN,
+                local_dir=constants.DATABASE_PATH,
+                force_download=True,
+            )
+        except Exception:
+            # If backup is enabled but no backup is found, delete local database to prevent confusion.
+            print("Couldn't find backup in remote dataset.")
+            print("Deleting local database for a fresh start.")
+            os.remove(constants.DATABASE_FILE)
+
+        # Start back-up scheduler
+        print("Starting back-up scheduler (save every 5 minutes)...")
+        scheduler = CommitScheduler(
+            repo_id=constants.BACKUP_DATASET_ID,  # type: ignore[arg-type]
+            folder_path=constants.DATABASE_PATH,
+            allow_patterns="database.db",
+            token=constants.HF_TOKEN,
+            private=True,
+            repo_type="dataset",
+            every=5,
+        )
+
+    engine = _get_engine()
+    SQLModel.metadata.create_all(engine)
+
+    yield
+
+    print("Closing database...")
+    global _ENGINE_SINGLETON
+    if _ENGINE_SINGLETON is not None:
+        _ENGINE_SINGLETON.dispose()
+        _ENGINE_SINGLETON = None
+
+    if constants.BACKUP_DB:
+        print("Pushing backup to remote dataset...")
+        scheduler.push_to_hub()
+
+
+def create_app() -> FastAPI:
+    # FastAPI app
+    app = FastAPI(lifespan=_database_lifespan)
+
+    # Set CORS headers
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=[
+            # Can't use "*" because frontend doesn't like it with "credentials: true"
+            "http://localhost:5173",
+            "http://0.0.0.0:9481",
+            "http://localhost:9481",
+            "http://127.0.0.1:9481",
+        ],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Mount frontend from dist directory (if configured)
+    if constants.SERVE_FRONTEND:
+        # Production => Serve frontend from dist directory
+        app.mount(
+            "/assets",
+            StaticFiles(directory=constants.FRONTEND_ASSETS_PATH),  # type: ignore[invalid-argument-type]
+            name="assets",
+        )
+
+        @app.get("/")
+        async def serve_frontend():
+            return FileResponse(constants.FRONTEND_INDEX_PATH)  # type: ignore[invalid-argument-type]
+
+    else:
+        # Development => Redirect to dev frontend
+        @app.get("/")
+        async def redirect_to_frontend():
+            return RedirectResponse("http://localhost:5173/")
+
+    # Set up Hugging Face OAuth
+    # To get OAuthInfo in an endpoint
+    attach_huggingface_oauth(app)
+
+    return app

backend/src/constants.py

@@ -13,9 +13,11 @@ DATABASE_URL = f"sqlite:///{DATABASE_FILE}"
 # In practice: is it running in a production environment?
 FRONTEND_PATH = os.getenv("FRONTEND_PATH")
 SERVE_FRONTEND = os.getenv("FRONTEND_PATH") is not None
-FRONTEND_ASSETS_PATH = os.path.join(FRONTEND_PATH, "assets") if SERVE_FRONTEND else None
+FRONTEND_ASSETS_PATH = (
+    os.path.join(FRONTEND_PATH, "assets") if FRONTEND_PATH is not None else None
+)
 FRONTEND_INDEX_PATH = (
-    os.path.join(FRONTEND_PATH, "index.html") if SERVE_FRONTEND else None
+    os.path.join(FRONTEND_PATH, "index.html") if FRONTEND_PATH is not None else None
 )
 
 
@@ -28,3 +30,9 @@ if SERVE_FRONTEND and (
         f"FRONTEND_PATH {FRONTEND_PATH} has not been built correctly. Please build the frontend first by running `pnpm build` from the 'frontend/' directory."
         " If you want to run the server in development mode, run `make dev` from the 'backend/' directory and `pnpm dev` from the 'frontend/' directory."
     )
+
+
+# Back-up Hub dataset (optional)
+BACKUP_DATASET_ID = os.getenv("BACKUP_DATASET_ID")
+HF_TOKEN = os.getenv("HF_TOKEN")
+BACKUP_DB = BACKUP_DATASET_ID is not None and HF_TOKEN is not None

backend/src/database.py

@@ -1,31 +0,0 @@
-from contextlib import contextmanager
-from typing import Generator
-
-from sqlalchemy.engine import Engine
-from sqlmodel import Session, SQLModel, create_engine
-
-from . import constants
-
-_ENGINE_SINGLETON: Engine | None = None
-
-
-def get_engine() -> Engine:
-    """Get the engine."""
-    global _ENGINE_SINGLETON
-    if _ENGINE_SINGLETON is None:
-        _ENGINE_SINGLETON = create_engine(constants.DATABASE_URL)
-    return _ENGINE_SINGLETON
-
-
-@contextmanager
-def get_session() -> Generator[Session, None, None]:
-    """Get a session from the engine."""
-    engine = get_engine()
-    with Session(engine) as session:
-        yield session
-
-
-def init_db() -> None:
-    """Initialize the database."""
-    engine = get_engine()
-    SQLModel.metadata.create_all(engine)

frontend/.env

@@ -1 +0,0 @@
-VITE_BACKEND_URL=http://127.0.0.1:8000

frontend/index.html

@@ -2,9 +2,9 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <link rel="icon" type="image/svg+xml" href="/src/assets/huggingface.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Vite + React + TS</title>
+    <title>FastAPI + React Space Template</title>
   </head>
   <body>
     <div id="root"></div>