Add docker + Space deployment

Dockerfile

@@ -0,0 +1,70 @@
+# =======================
+# 1️⃣ Frontend build stage
+# =======================
+FROM node:22-slim AS frontend-builder
+
+# Install pnpm globally
+RUN corepack enable && corepack prepare pnpm@latest --activate
+
+# Set working directory
+WORKDIR /app/frontend
+
+# Copy package files first for caching
+COPY frontend/pnpm-lock.yaml frontend/package.json ./
+
+# Install dependencies (prod only for frontend)
+RUN pnpm install --frozen-lockfile
+
+# Copy the rest of the frontend source
+COPY frontend/ ./
+
+# Build frontend
+ENV VITE_APP_ENV=production
+RUN pnpm build
+
+
+# =======================
+# 2️⃣ Backend build stage
+# =======================
+FROM python:3.12-slim AS backend-builder
+
+# Install uv (fast Python package installer)
+RUN pip install --no-cache-dir uv
+
+# Set working directory
+WORKDIR /app
+
+# Copy backend requirements and install (no dev deps)
+COPY backend/pyproject.toml backend/uv.lock ./backend/
+RUN cd backend && uv pip install --no-cache-dir --system .
+
+# Copy backend source
+COPY backend/ ./backend/
+
+# Copy built frontend from stage 1
+COPY --from=frontend-builder /app/frontend/dist ./frontend/dist
+
+# =======================
+# 3️⃣ Production runtime
+# =======================
+FROM python:3.12-slim
+
+# Create non-root user
+RUN useradd -m appuser
+WORKDIR /app
+
+# Copy installed packages and app
+COPY --from=backend-builder /usr/local /usr/local
+COPY --from=backend-builder /app /app
+
+# Set frontend path for FastAPI
+ENV FRONTEND_PATH=/app/frontend/dist
+
+# Switch to non-root user
+USER appuser
+
+# Expose port (adjust if needed)
+EXPOSE 8000
+
+# Run FastAPI via uvicorn
+CMD ["uvicorn", "backend.src.app:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -0,0 +1,70 @@
+---
+title: FastAPI + React Template
+emoji: 💻
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 8000
+---
+
+# docker-space-fastapi-react
+
+This repo is a template to run a FastAPI server hosting a React+Tailwind app in a Hugging Face Space.
+
+Spaces are very well suited to vibe-code demos using Cursor, Lovable, Claude Code, etc. The hardest past is often to correctly configure the tooltip to make it work in the first place. This repo is intended to solve that.
+
+## Getting started
+
+The backend (Python + FastAPI) and the frontend (TS + React + Tailwind) are located respectively in the `backend/` and `frontend/` folder.
+
+### Backend
+
+To run the backend, you'll need `uv` and Python3.12 installed.
+Install dependencies with:
+
+```bash
+uv venv
+make install
+```
+
+And then run the backend server with:
+
+```bash
+make dev
+```
+
+For more details about backend development, check out [this README](./backend/README.md).
+
+### Frontend
+
+To run the frontend, you'll need nodeJS + pnpm installed.
+
+Install dependencies with:
+
+```bash
+pnpm install
+```
+
+And then run the frontend app with:
+
+```bash
+pnpm dev
+```
+
+Once both parts are running, go to the frontend URL. You should see a green "Backend Online" message in the top-right corner. Note that this message is only visible in development mode. When running in a Space, it won't be shown to your end users.
+
+For more details about frontend development, check out [this README](./frontend/README.md).
+
+## Deploy
+
+This repo is meant to be run in a [Docker Space](https://huggingface.co/docs/hub/spaces-sdks-docker).
+Configuration should be automatically done if you clone the on the Hugging Face Hub.
+
+If you want to run it on your own, you can use Docker:
+
+```bash
+docker build -t fastapi-react-space .
+docker run -p 8000:8000 fastapi-react-space
+```
+
+Note that when running in Docker, the app runs in production mode without hot-reloading.

backend/Makefile

@@ -10,4 +10,7 @@ quality:
 
 style:
 	ruff format src
-	ruff check --fix src
+	ruff check --fix src
+
+preview:
+	FRONTEND_PATH=../frontend/dist/ uv run uvicorn src.app:app

backend/src/app.py

@@ -1,5 +1,9 @@
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from . import constants
 
 app = FastAPI()
 
@@ -12,6 +16,18 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+# Mount static files from dist directory (if configured)
+if constants.SERVE_FRONTEND:
+    app.mount(
+        "/assets",
+        StaticFiles(directory=constants.FRONTEND_ASSETS_PATH),
+        name="assets",
+    )
+
+    @app.get("/")
+    async def serve_frontend():
+        return FileResponse(constants.FRONTEND_INDEX_PATH)
+
 
 @app.get("/api/health")
 async def health():

backend/src/constants.py

@@ -0,0 +1,20 @@
+import os
+
+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_INDEX_PATH = (
+    os.path.join(FRONTEND_PATH, "index.html") if SERVE_FRONTEND else None
+)
+
+
+if SERVE_FRONTEND and (
+    not os.path.exists(FRONTEND_PATH)
+    or not os.path.exists(FRONTEND_ASSETS_PATH)
+    or not os.path.exists(FRONTEND_INDEX_PATH)
+):
+    raise FileNotFoundError(
+        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."
+    )

frontend/package.json

@@ -3,6 +3,7 @@
   "private": true,
   "version": "0.0.0",
   "type": "module",
+  "packageManager": "[email protected]",
   "scripts": {
     "dev": "vite",
     "build": "tsc -b && vite build",

frontend/src/App.tsx

@@ -1,6 +1,6 @@
 import { useState } from "react";
 import reactLogo from "./assets/react.svg";
-import viteLogo from "/vite.svg";
+import viteLogo from "./assets/vite.svg";
 import { BackendHealthCheck } from "./components/BackendHealthCheck";
 
 function App() {
@@ -9,7 +9,7 @@ function App() {
   return (
     <div className="min-h-screen bg-gray-900 text-white flex items-center justify-center">
       <div className="max-w-4xl mx-auto p-8 text-center">
-        {/* Backend Status Indicator */}
+        {/* Backend Status Indicator - Only shown in development mode */}
         <BackendHealthCheck />
 
         <div className="flex justify-center space-x-8 mb-8">

frontend/src/components/BackendHealthCheck.tsx

@@ -9,7 +9,14 @@ interface BackendHealthCheckProps {
 export function BackendHealthCheck({ 
   checkInterval = APP_CONFIG.HEALTH_CHECK_INTERVAL
 }: BackendHealthCheckProps) {
+  // Only render in development mode
+  if (import.meta.env.PROD) {
+    return null;
+  }
+
   const [backendStatus, setBackendStatus] = useState<'loading' | 'online' | 'offline'>('loading');
+  const [showTooltip, setShowTooltip] = useState(false);
+  const [copied, setCopied] = useState(false);
   const healthCheckUrl = `${BACKEND_URL}/api/health`;
 
   useEffect(() => {
@@ -39,6 +46,17 @@ export function BackendHealthCheck({
     return () => clearInterval(interval);
   }, [healthCheckUrl, checkInterval]);
 
+  const handleCopyCode = async () => {
+    const codeText = `cd backend/\nmake install\nmake backend`;
+    try {
+      await navigator.clipboard.writeText(codeText);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch (err) {
+      console.error('Failed to copy text: ', err);
+    }
+  };
+
   const getStatusColor = () => {
     switch (backendStatus) {
       case 'online':
@@ -66,9 +84,62 @@ export function BackendHealthCheck({
   };
 
   return (
-    <div className="absolute top-4 right-4 flex items-center space-x-2 bg-gray-800 rounded-lg px-3 py-2">
-      <div className={`w-3 h-3 rounded-full ${getStatusColor()} animate-pulse`}></div>
-      <span className="text-sm font-medium">{getStatusText()}</span>
+    <div className="absolute top-4 right-4">
+      <div 
+        className="relative flex items-center space-x-2 bg-gray-800 rounded-lg px-3 py-2 cursor-pointer hover:bg-gray-700 transition-colors"
+        onMouseEnter={() => backendStatus === 'offline' && setShowTooltip(true)}
+        onMouseLeave={() => setShowTooltip(false)}
+      >
+        <div className={`w-3 h-3 rounded-full ${getStatusColor()} animate-pulse`}></div>
+        <span className="text-sm font-medium">{getStatusText()}</span>
+        
+        {/* Info icon when backend is offline */}
+        {backendStatus === 'offline' && (
+                <svg className="w-5 h-5 text-red-400" fill="currentColor" viewBox="0 0 20 20">
+                <path fillRule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7 4a1 1 0 11-2 0 1 1 0 012 0zm-1-9a1 1 0 00-1 1v4a1 1 0 102 0V6a1 1 0 00-1-1z" clipRule="evenodd" />
+              </svg>
+        )}
+        
+        {/* Tooltip for offline backend */}
+        {showTooltip && backendStatus === 'offline' && (
+          <div 
+            className="absolute top-full right-0 mt-2 w-fit bg-gray-900 text-white rounded-lg p-4 shadow-xl border border-gray-700 z-50"
+            onMouseEnter={() => setShowTooltip(true)}
+            onMouseLeave={() => setShowTooltip(false)}
+          >
+            <div className="flex items-start space-x-3">
+              <div className="flex-1 min-w-0">
+                <h3 className="text-sm font-semibold text-400 mb-3 text-left">Start the server with:</h3>
+                <div className="relative">
+                  <code className="text-xs bg-gray-800 text-green-400 px-3 py-2 rounded font-mono block w-fit overflow-x-auto text-left pr-12">
+                    cd backend/<br/>
+                    make install<br/>
+                    make backend
+                  </code>
+                  <button
+                    onClick={handleCopyCode}
+                    className="absolute top-1 right-1 p-1 bg-gray-700 hover:bg-gray-600 rounded text-gray-300 hover:text-white transition-colors"
+                    title="Copy to clipboard"
+                  >
+                    {copied ? (
+                      <svg className="w-4 h-4 text-green-400" fill="currentColor" viewBox="0 0 20 20">
+                        <path fillRule="evenodd" d="M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z" clipRule="evenodd" />
+                      </svg>
+                    ) : (
+                      <svg className="w-4 h-4" fill="currentColor" viewBox="0 0 20 20">
+                        <path d="M8 3a1 1 0 011-1h2a1 1 0 110 2H9a1 1 0 01-1-1z" />
+                        <path d="M6 3a2 2 0 00-2 2v11a2 2 0 002 2h8a2 2 0 002-2V5a2 2 0 00-2-2 3 3 0 01-3 3H9a3 3 0 01-3-3z" />
+                      </svg>
+                    )}
+                  </button>
+                </div>
+              </div>
+            </div>
+            {/* Arrow pointing up */}
+            <div className="absolute bottom-full right-4 w-0 h-0 border-l-4 border-r-4 border-b-4 border-transparent border-b-gray-900"></div>
+          </div>
+        )}
+      </div>
     </div>
   );
 }