File size: 2,541 Bytes
59329ee 91af612 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 | # Hugging Face Space Deployment Guidelines & Best Practices
## 1. Deployment Configuration
### Target Space
- **Profile:** `Leon4gr45`
- **Space:** `builder`
- **Full Identifier:** `Leon4gr45/builder`
- **Frontend Port:** `7860` (mandatory for all Hugging Face Spaces)
### Deployment Method
We use the **Docker SDK** for flexibility, utilizing a standard `Dockerfile` configured to run Next.js standalone on port `7860`.
### HF Token
- The token is read from the environment variable (never hardcode it).
### Required Files
- `Dockerfile` (binds the app to port `7860`)
- `README.md` (includes Hugging Face YAML frontmatter)
- `.hfignore` (excludes unnecessary files to prevent repository limit issues)
- `Agent.md` (this file, detailing current practices)
---
## 2. API Exposure and Documentation
### Mandatory Endpoints
The following endpoints must be accessible publicly without any redirection/authentication block (configured in Next.js middleware):
- **`/health`**
- **Method:** GET
- **Purpose:** Health check returning HTTP 200 once Next.js server is ready. Necessary for Hugging Face to transition the Space status to *running*.
- **Response:**
```json
{
"ok": true,
"name": "osw-studio",
"version": "1.84.0",
"mode": "browser",
"timestamp": "2026-07-16T12:00:00.000Z"
}
```
- **`/api-docs`**
- **Method:** GET
- **Purpose:** Serve documentation or routes specification of the available APIs.
- **Response:** JSON list of the endpoints.
### Functional Endpoints
All the available functional endpoints listed in `/health` under the endpoint groups (like `auth`, `public`, `analytics`, etc.) are supported.
---
## 3. Tricks & Troubleshooting
- **Large Upload / Storage Limit (Max: 1 GB):**
- Since standard `hf upload` without exclusions attempts to scan/upload local `node_modules` and `.next` build files, it can hit the 1 GB storage limit or fail on string limit in JS wrapper.
- **Fix:** Always explicitly set up `.hfignore` or use `--exclude` to ignore large local directories such as `node_modules/*`, `.next/*`, `.git/*`.
- Deployment Command:
```bash
hf upload Leon4gr45/builder . --repo-type=space --token=$HF_TOKEN --exclude="node_modules/*" --exclude=".next/*" --exclude=".git/*"
```
- **Middleware Matcher Exclusion:**
- Standard Next.js matcher should explicitly allow `/health` and `/api-docs` so Hugging Face load balancers can reach them without running into authentication loops/redirects.
# Force rebuild comment 1
|