chore: production-readiness pass — add missing release files, clean up code

New files:
- .env.example: full configuration reference with inline docs
- .gitattributes: normalize line endings (LF), mark binaries
- CHANGELOG.md: v1.0.0 release history + unreleased roadmap
- CODE_OF_CONDUCT.md: community standards
- SECURITY.md: vulnerability reporting, secrets mgmt, known limitations
- docker-compose.yml: local development with hot-reload volume mounts

Code fixes:
- health-server.js: remove dead .replace() call on template literal output
- Dockerfile: remove dashboard.html COPY (nginx no longer serves it)
- dashboard.html: delete orphaned file

Docs:
- CONTRIBUTING.md: full rewrite with file overview table, docker-compose workflow, hot-reload note
- README.md: fix stale worker count caveat (1 worker, not 2)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.env.example

@@ -0,0 +1,105 @@
+# ============================================================================
+# HuggingFlow — DeerFlow Research Agent on Hugging Face Spaces
+# Configuration Reference
+# ============================================================================
+# Copy this file to .env for local Docker development.
+# On HF Spaces, set these as Secrets in Settings → Variables and Secrets.
+# NEVER commit your .env file — it contains real credentials.
+# ============================================================================
+
+# ============================================================================
+# LLM Provider (REQUIRED)
+# ============================================================================
+
+# Model in "provider/model-name" format.
+# See README for full provider list.
+LLM_MODEL=openai/gpt-4o
+
+# API key for the chosen provider.
+LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# ============================================================================
+# Search Tools (Optional — highly recommended)
+# ============================================================================
+
+# Serper — real Google Search results. 2,500 free queries/month.
+# https://serper.dev
+# SERPER_API_KEY=xxxxxxxxxxxxxxxxxxxx
+
+# Tavily — alternative web search with free tier.
+# https://tavily.com
+# TAVILY_API_KEY=tvly-xxxxxxxxxxxxxxxxxxxx
+
+# Jina AI — better web page fetching and reading.
+# https://jina.ai
+# JINA_API_KEY=jina_xxxxxxxxxxxxxxxxxxxx
+
+# ============================================================================
+# Authentication & Security
+# ============================================================================
+
+# JWT signing secret for DeerFlow auth. Sessions survive restarts if this is set.
+# Generate: openssl rand -base64 32
+# AUTH_JWT_SECRET=your-random-secret-here-minimum-32-characters
+
+# ============================================================================
+# Data Persistence (Optional — required for threads to survive restarts)
+# ============================================================================
+
+# Your Hugging Face API token (needs Write access).
+# https://huggingface.co/settings/tokens
+# HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# HF Dataset repo name for backups (auto-created as private).
+# Will be: {your-hf-username}/{BACKUP_DATASET_NAME}
+BACKUP_DATASET_NAME=huggingflow-backup
+
+# How often to sync to HF Dataset (seconds). Default: 10 minutes.
+SYNC_INTERVAL=600
+
+# ============================================================================
+# Custom / Self-hosted LLM (Optional)
+# ============================================================================
+
+# OpenAI-compatible base URL for any custom or self-hosted endpoint.
+# When set, uses LLM_API_KEY as the API key and LLM_MODEL as the model name.
+# CUSTOM_BASE_URL=https://your-llm-endpoint.example.com/v1
+
+# ============================================================================
+# Cloudflare Integration (Optional)
+# ============================================================================
+
+# Cloudflare API token with Workers Edit permission.
+# Enables: (1) outbound proxy Worker — bypasses HF Spaces IP blocks on some APIs.
+#          (2) keep-awake cron Worker — pings /health every 10 min to prevent sleep.
+# https://dash.cloudflare.com/profile/api-tokens
+# CLOUDFLARE_WORKERS_TOKEN=your_cloudflare_api_token
+
+# Skip auto-setup and use an existing Cloudflare Worker URL directly.
+# CLOUDFLARE_PROXY_URL=https://your-worker.your-subdomain.workers.dev
+
+# ============================================================================
+# Startup Timeouts (Optional)
+# ============================================================================
+
+# Max seconds to wait for the DeerFlow backend (FastAPI) to start.
+BACKEND_READY_TIMEOUT=120
+
+# Max seconds to wait for the DeerFlow frontend (Next.js) to start.
+FRONTEND_READY_TIMEOUT=120
+
+# ============================================================================
+# HuggingFace Spaces — Automatically injected by the platform
+# ============================================================================
+
+# These are set automatically by HF Spaces at runtime. Do not set manually.
+# SPACE_ID=your-username/your-space-name
+# SPACE_HOST=your-username-your-space-name.hf.space
+# SPACE_AUTHOR_NAME=your-hf-username
+
+# ============================================================================
+# Privacy / Telemetry
+# ============================================================================
+
+# DeerFlow is self-hosted — no external telemetry. These are informational only.
+DO_NOT_TRACK=1

.gitattributes

@@ -0,0 +1,43 @@
+# Normalize line endings to LF everywhere
+* text=auto eol=lf
+
+# Force LF for shell scripts (Windows editors sometimes write CRLF)
+*.sh text eol=lf
+
+# Force LF for Python
+*.py text eol=lf
+
+# Force LF for JS/TS
+*.js text eol=lf
+*.ts text eol=lf
+*.tsx text eol=lf
+*.jsx text eol=lf
+*.json text eol=lf
+
+# Force LF for config / markup
+*.yaml text eol=lf
+*.yml text eol=lf
+*.md text eol=lf
+*.conf text eol=lf
+*.txt text eol=lf
+*.html text eol=lf
+*.css text eol=lf
+
+# Dockerfiles
+Dockerfile text eol=lf
+*.dockerfile text eol=lf
+
+# Binary — no diff, no merge
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.otf binary
+*.eot binary
+*.gz binary
+*.zip binary
+*.tar binary

CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to HuggingFlow are documented here.
+
+## [1.0.0] - 2026-05-08
+
+### Added
+
+- Initial public release of HuggingFlow
+- DeerFlow v2 (ByteDance) deployed as a single-container Hugging Face Space
+- Pre-built GHCR image strategy — pulls `ghcr.io/bytedance/deer-flow-backend:latest` and `ghcr.io/bytedance/deer-flow-frontend:latest` instead of compiling from source; build time ~5 min (was 30+ min)
+- Multi-provider LLM support: OpenAI, Anthropic, Google Gemini, DeepSeek, Groq, Mistral, xAI/Grok, OpenRouter, Qwen/Alibaba, Moonshot/Kimi, any OpenAI-compatible endpoint
+- Pluggable search: Serper (Google), Tavily, DuckDuckGo fallback
+- Live status dashboard at `/` — tile grid showing DeerFlow App, Model, Runtime, Search, Backup, Keep Awake; auto-refreshes every 30 s
+- HF Dataset backup/restore via `deerflow-sync.py` — syncs SQLite DB + workspace files on interval and graceful shutdown
+- Cloudflare outbound proxy — routes backend traffic through a Cloudflare Worker to bypass HF Spaces IP blocks
+- Cloudflare keep-awake cron — Worker pings `/health` every 10 min to prevent free-tier sleep
+- JWT auth via DeerFlow v2 — admin account created at `/setup` on first boot
+- nginx reverse proxy (port 7861) — routes `/api/*` to FastAPI backend, `/*` to Next.js frontend, LangGraph SDK alias at `/api/langgraph/*`
+- health-server.js (port 7860, public) — status dashboard + transparent reverse proxy to nginx + WebSocket upgrade passthrough
+- Graceful shutdown with final HF Dataset sync
+- `docker-compose.yml` for local development
+- `.env.example` configuration reference
+- MIT License
+
+### Fixed
+
+- `DEER_FLOW_TRUSTED_ORIGINS` must be explicitly set for pre-built frontend image (sha `af6e48cc`); without it, zod schema validation fails silently → "Application error" on every Next.js page
+- `--workers 1` on uvicorn prevents SQLite `CREATE TABLE` race condition with multiple workers
+- Next.js `.bin/next` is a shell shim — must not be called with `node` prefix
+- nginx `alias` on a file path appends `index.html` — replaced with `root` + `try_files`
+
+## [Unreleased]
+
+### Planned
+
+- Multi-user admin management UI
+- Backup versioning and restore from specific snapshots
+- Prometheus / Grafana monitoring integration
+- External PostgreSQL support option
+- GitHub Actions CI for image freshness checks
+- Kubernetes deployment manifests

CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Code of Conduct
+
+## Our Pledge
+
+We pledge to make participation in HuggingFlow a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity, level of experience, nationality, personal appearance, race, religion, or sexual identity.
+
+## Our Standards
+
+**Positive behavior includes:**
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experience
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy toward other contributors
+
+**Unacceptable behavior includes:**
+- Trolling, insulting, or derogatory comments
+- Harassment in any form, public or private
+- Publishing others' private information without explicit permission
+- Other conduct that could reasonably be considered inappropriate
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject comments, commits, code, issues, and other contributions that violate this Code of Conduct. Repeated violations may result in a temporary or permanent ban.
+
+## Scope
+
+This Code of Conduct applies in all project spaces (GitHub issues, pull requests, discussions) and in public spaces when an individual represents the project.
+
+## Reporting
+
+Report violations by opening a private GitHub issue or contacting the maintainers directly. All reports will be handled confidentially.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

CONTRIBUTING.md

@@ -1,38 +1,75 @@
 # Contributing to HuggingFlow
 
-Thanks for your interest in contributing!
+Thank you for your interest in contributing!
 
-## How to contribute
+## Bug Reports
+
+1. Check existing [issues](https://github.com/somratpro/HuggingFlow/issues) first
+2. Open a new issue with:
+   - Clear title and description
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Your `LLM_MODEL` provider (no keys please)
+   - HF Space tier or Docker version if relevant
+
+## Pull Requests
 
 1. Fork the repository
 2. Create a feature branch: `git checkout -b feat/your-feature`
-3. Make your changes and test locally with `docker build .`
-4. Commit with a clear message
-5. Open a pull request describing what changed and why
+3. Make changes and test locally (see below)
+4. Commit using [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
+5. Push and open a Pull Request describing what changed and why
 
-## Development setup
+Open an issue first for large or architectural changes.
 
-You need Docker and a valid `LLM_MODEL` + `LLM_API_KEY` to test locally:
+## Local Development
 
 ```bash
-docker build -t huggingflow .
-docker run --rm -p 7860:7860 \
-  -e LLM_MODEL=openai/gpt-4o \
-  -e LLM_API_KEY=sk-... \
-  huggingflow
+# Clone
+git clone https://github.com/somratpro/HuggingFlow
+cd HuggingFlow
+
+# Configure
+cp .env.example .env
+# Edit .env — set LLM_MODEL, LLM_API_KEY, optionally SERPER_API_KEY
+
+# Build and run
+docker-compose up --build
+
+# Dashboard
+open http://localhost:7860/
+
+# Create admin account
+open http://localhost:7860/setup
+
+# Research workspace
+open http://localhost:7860/workspace
+
+# Health check
+curl http://localhost:7860/health
 ```
 
-Open `http://localhost:7860` for the DeerFlow app,  
-or `http://localhost:7860/dashboard` for the status dashboard.
+Hot-reload for orchestration scripts: `docker-compose.yml` volume-mounts `start.sh`, `health-server.js`, `deerflow-sync.py`, and `nginx.conf` — edit and restart the container without a full rebuild.
 
-## Guidelines
+## File Overview
 
-- Keep changes minimal and focused
-- Test with at least one LLM provider before submitting
-- Update `README.md` if you add new environment variables or features
-- Open an issue first for large changes
+| File | Purpose |
+|------|---------|
+| `Dockerfile` | Container build — pulls pre-built DeerFlow GHCR images |
+| `start.sh` | Startup orchestration: config generation, service sequencing, graceful shutdown |
+| `health-server.js` | Port 7860 public gateway — status dashboard + transparent reverse proxy to nginx |
+| `nginx.conf` | nginx reverse proxy (port 7861) — routes API, frontend, LangGraph alias |
+| `deerflow-sync.py` | HF Dataset backup/restore for SQLite DB + workspace files |
+| `cloudflare-proxy.js` | Node.js `http`/`https` agent that routes traffic through a Cloudflare Worker |
+| `cloudflare-proxy-setup.py` | Auto-provisions the Cloudflare outbound proxy Worker |
+| `cloudflare-keepalive-setup.py` | Auto-provisions the Cloudflare keep-awake cron Worker |
+| `docker-compose.yml` | Local development setup |
+| `.env.example` | Full configuration reference with inline documentation |
 
-## Reporting issues
+## Guidelines
 
-Use [GitHub Issues](https://github.com/somratpro/HuggingFlow/issues).  
-Include: what you expected, what happened, and your `LLM_MODEL` provider (no keys).
+- Keep changes minimal and focused — avoid touching unrelated files
+- Test with at least one LLM provider before submitting
+- Update `README.md` and `.env.example` if you add new environment variables
+- Update `CHANGELOG.md` with a summary under `[Unreleased]`
+- Security issues: see [SECURITY.md](SECURITY.md) — do not open public issues for vulnerabilities

Dockerfile

@@ -96,7 +96,6 @@ COPY --from=source --chown=1000:1000 /src/config.example.yaml /app/config.exampl
 
 # ── Copy HuggingFlow runtime scripts ─────────────────────────────
 COPY --chown=1000:1000 nginx.conf                    /etc/nginx/nginx.conf
-COPY --chown=1000:1000 dashboard.html                /app/dashboard.html
 COPY --chown=1000:1000 start.sh                      /app/start.sh
 COPY --chown=1000:1000 deerflow-sync.py              /app/deerflow-sync.py
 COPY --chown=1000:1000 health-server.js              /app/health-server.js

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 somratpro
+Copyright (c) 2026 somratpro
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -167,6 +167,7 @@ Serper is strongly recommended for research quality. Sign up at [serper.dev](htt
 HF Spaces shares IPs that some APIs block. The Cloudflare outbound proxy routes backend HTTP requests through a Cloudflare Worker, giving you a clean egress IP.
 
 **Setup:**
+
 1. Get a Cloudflare API token with **Workers Edit** permission
 2. Set `CLOUDFLARE_WORKERS_TOKEN` in your Space secrets
 3. On next start, `cloudflare-proxy-setup.py` auto-creates the Worker and sets `CLOUDFLARE_PROXY_URL`
@@ -236,6 +237,7 @@ nginx
 | 3000 | Next.js frontend | internal only |
 
 **Images used:**
+
 - `ghcr.io/bytedance/deer-flow-backend:latest` — pre-built Python backend + `.venv`
 - `ghcr.io/bytedance/deer-flow-frontend:latest` — pre-built Next.js + `node_modules`
 - No source compilation — build time ~5 min instead of 30+ min

SECURITY.md

@@ -0,0 +1,73 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.x     | ✅ Yes    |
+
+## Reporting a Vulnerability
+
+**Do NOT open a public GitHub issue for security vulnerabilities.**
+
+Instead, report privately:
+
+- Open a [GitHub Security Advisory](https://github.com/somratpro/HuggingFlow/security/advisories/new) (preferred)
+- Or email the maintainer directly (see GitHub profile)
+
+Include:
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+We will respond within 48 hours and aim to patch critical issues within 7 days.
+
+## Security Best Practices
+
+### Secrets Management
+
+- **Never commit secrets to git** — use HF Space secrets or environment variables only
+- `LLM_API_KEY`: Store as HF Space secret — never in code or Dockerfile `ENV`
+- `HF_TOKEN`: Same — HF Space secret only
+- `AUTH_JWT_SECRET`: Generate a strong random value (`openssl rand -base64 32`); without it, a new secret is generated on every restart (sessions lost)
+- `CLOUDFLARE_WORKERS_TOKEN`: HF Space secret only
+- Rotate all tokens immediately if accidentally exposed
+
+### Network Security
+
+- `umask 0077` enforced at startup — all files created owner-only by default
+- nginx binds on `127.0.0.1:7861` (internal only) — not exposed externally
+- FastAPI backend binds on `127.0.0.1:8001` (internal only)
+- Next.js frontend binds on `127.0.0.1:3000` (internal only)
+- Only `health-server.js` on port `7860` is publicly accessible
+
+### Container Security
+
+- Non-root user `user` (UID 1000) — required by HF Spaces and a security best practice
+- Based on `python:3.12-slim-bookworm` — minimal attack surface
+- No secrets baked into the image — all configuration via environment variables
+- Cloudflare proxy uses an auto-generated shared secret for Worker authentication
+
+### DeerFlow Auth
+
+- DeerFlow v2 uses JWT auth; all `/api/*` routes require authentication
+- Create your admin account at `/setup` immediately after first deploy — it is only accessible until an admin exists
+- Set `AUTH_JWT_SECRET` to a strong random value or sessions reset on every restart
+
+### HF Dataset Backup
+
+- Backup dataset is created as **private** automatically
+- The archive contains your full SQLite database (threads, messages, API key hashes) — protect your `HF_TOKEN` and dataset access
+- Do not share the backup dataset URL publicly
+
+### Cloudflare Worker Proxy
+
+- The Cloudflare Worker proxy can observe proxied HTTP traffic — review the `cloudflare-proxy.js` source before enabling
+- The Worker is scoped to specific domains; set `CLOUDFLARE_PROXY_DOMAINS` to restrict further
+
+## Known Limitations
+
+- **HF Spaces free tier is public** — anyone can reach your Space URL. DeerFlow's auth (`/setup` → JWT) protects the API and UI, but the dashboard at `/` and `/health` are intentionally unauthenticated
+- **Ephemeral storage without backup** — if `HF_TOKEN` is not set, all threads are lost on restart
+- **Single-worker backend** — `uvicorn --workers 1` prevents SQLite race conditions; for high-concurrency workloads, consider a dedicated server with PostgreSQL

dashboard.html

@@ -1,308 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>HuggingFlow — DeerFlow on Hugging Face</title>
-  <style>
-    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
-
-    :root {
-      --bg: #0f1117;
-      --surface: #1a1d27;
-      --border: #2a2d3e;
-      --accent: #ff9d00;
-      --accent2: #7c3aed;
-      --text: #e2e8f0;
-      --muted: #64748b;
-      --green: #22c55e;
-      --card: #161927;
-    }
-
-    body {
-      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-      background: var(--bg);
-      color: var(--text);
-      min-height: 100vh;
-      display: flex;
-      flex-direction: column;
-      align-items: center;
-      justify-content: center;
-      padding: 2rem 1rem;
-    }
-
-    .container { max-width: 720px; width: 100%; }
-
-    /* ── Header ─────────────────────────────────────────── */
-    .header {
-      text-align: center;
-      margin-bottom: 3rem;
-    }
-
-    .logo {
-      font-size: 3.5rem;
-      line-height: 1;
-      margin-bottom: 0.75rem;
-      filter: drop-shadow(0 0 24px rgba(255,157,0,0.4));
-    }
-
-    .title {
-      font-size: 2rem;
-      font-weight: 700;
-      letter-spacing: -0.02em;
-      background: linear-gradient(135deg, #ff9d00 0%, #ff6b35 50%, #7c3aed 100%);
-      -webkit-background-clip: text;
-      -webkit-text-fill-color: transparent;
-      background-clip: text;
-      margin-bottom: 0.5rem;
-    }
-
-    .subtitle {
-      color: var(--muted);
-      font-size: 0.95rem;
-    }
-
-    .subtitle a {
-      color: var(--accent);
-      text-decoration: none;
-    }
-
-    .subtitle a:hover { text-decoration: underline; }
-
-    /* ── Status pill ────────────────────────────────────── */
-    .status-pill {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.5rem;
-      background: rgba(34,197,94,0.1);
-      border: 1px solid rgba(34,197,94,0.3);
-      color: var(--green);
-      font-size: 0.8rem;
-      font-weight: 600;
-      padding: 0.3rem 0.85rem;
-      border-radius: 999px;
-      margin-bottom: 2rem;
-      letter-spacing: 0.04em;
-      text-transform: uppercase;
-    }
-
-    .dot {
-      width: 7px; height: 7px;
-      background: var(--green);
-      border-radius: 50%;
-      animation: pulse 2s ease-in-out infinite;
-    }
-
-    @keyframes pulse {
-      0%,100% { opacity: 1; transform: scale(1); }
-      50%      { opacity: 0.5; transform: scale(0.8); }
-    }
-
-    /* ── Primary CTA ────────────────────────────────────── */
-    .cta-row {
-      display: flex;
-      gap: 0.75rem;
-      justify-content: center;
-      margin-bottom: 2.5rem;
-      flex-wrap: wrap;
-    }
-
-    .btn {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.45rem;
-      font-size: 0.9rem;
-      font-weight: 600;
-      padding: 0.65rem 1.4rem;
-      border-radius: 8px;
-      text-decoration: none;
-      transition: all 0.15s ease;
-      border: 1px solid transparent;
-    }
-
-    .btn-primary {
-      background: linear-gradient(135deg, #ff9d00, #ff6b35);
-      color: #fff;
-      box-shadow: 0 4px 16px rgba(255,157,0,0.3);
-    }
-
-    .btn-primary:hover {
-      transform: translateY(-1px);
-      box-shadow: 0 6px 24px rgba(255,157,0,0.45);
-    }
-
-    .btn-ghost {
-      background: var(--surface);
-      color: var(--text);
-      border-color: var(--border);
-    }
-
-    .btn-ghost:hover {
-      background: var(--border);
-      transform: translateY(-1px);
-    }
-
-    /* ── Info grid ──────────────────────────────────────── */
-    .grid {
-      display: grid;
-      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-      gap: 1rem;
-      margin-bottom: 2rem;
-    }
-
-    .card {
-      background: var(--card);
-      border: 1px solid var(--border);
-      border-radius: 12px;
-      padding: 1.25rem 1.5rem;
-    }
-
-    .card-label {
-      font-size: 0.7rem;
-      font-weight: 600;
-      text-transform: uppercase;
-      letter-spacing: 0.08em;
-      color: var(--muted);
-      margin-bottom: 0.5rem;
-    }
-
-    .card-value {
-      font-size: 1rem;
-      font-weight: 600;
-      color: var(--text);
-    }
-
-    .card-value.mono { font-family: "SF Mono", "Fira Code", monospace; font-size: 0.85rem; }
-
-    /* ── Routes table ───────────────────────────────────── */
-    .routes {
-      background: var(--card);
-      border: 1px solid var(--border);
-      border-radius: 12px;
-      overflow: hidden;
-      margin-bottom: 2rem;
-    }
-
-    .routes-header {
-      padding: 0.85rem 1.5rem;
-      font-size: 0.75rem;
-      font-weight: 600;
-      text-transform: uppercase;
-      letter-spacing: 0.08em;
-      color: var(--muted);
-      border-bottom: 1px solid var(--border);
-    }
-
-    .route-row {
-      display: flex;
-      align-items: center;
-      justify-content: space-between;
-      padding: 0.85rem 1.5rem;
-      border-bottom: 1px solid var(--border);
-      text-decoration: none;
-      color: var(--text);
-      transition: background 0.1s;
-    }
-
-    .route-row:last-child { border-bottom: none; }
-
-    .route-row:hover { background: var(--border); }
-
-    .route-path {
-      font-family: "SF Mono", "Fira Code", monospace;
-      font-size: 0.85rem;
-      color: var(--accent);
-    }
-
-    .route-desc { font-size: 0.85rem; color: var(--muted); }
-
-    .route-arrow { color: var(--muted); font-size: 0.8rem; }
-
-    /* ── Footer ─────────────────────────────────────────── */
-    .footer {
-      text-align: center;
-      font-size: 0.78rem;
-      color: var(--muted);
-    }
-
-    .footer a { color: var(--muted); }
-    .footer a:hover { color: var(--text); }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <div class="header">
-      <div class="logo">🦌</div>
-      <div class="title">HuggingFlow</div>
-      <p class="subtitle">
-        <a href="https://github.com/bytedance/deer-flow" target="_blank" rel="noopener">DeerFlow</a>
-        research agent · hosted on Hugging Face Spaces
-      </p>
-    </div>
-
-    <div style="text-align:center">
-      <span class="status-pill"><span class="dot"></span>Running</span>
-    </div>
-
-    <div class="cta-row">
-      <a href="/workspace" class="btn btn-primary">⚡ Open Workspace</a>
-      <a href="/setup"     class="btn btn-ghost">🔧 Admin Setup</a>
-      <a href="/docs"      class="btn btn-ghost">📖 API Docs</a>
-    </div>
-
-    <div class="grid">
-      <div class="card">
-        <div class="card-label">Stack</div>
-        <div class="card-value">DeerFlow v2</div>
-      </div>
-      <div class="card">
-        <div class="card-label">Backend</div>
-        <div class="card-value mono">FastAPI · port 8001</div>
-      </div>
-      <div class="card">
-        <div class="card-label">Frontend</div>
-        <div class="card-value mono">Next.js · port 3000</div>
-      </div>
-      <div class="card">
-        <div class="card-label">Proxy</div>
-        <div class="card-value mono">nginx · port 7861</div>
-      </div>
-    </div>
-
-    <div class="routes">
-      <div class="routes-header">Available Routes</div>
-      <a href="/"          class="route-row">
-        <span class="route-path">/</span>
-        <span class="route-desc">This dashboard</span>
-        <span class="route-arrow">→</span>
-      </a>
-      <a href="/workspace" class="route-row">
-        <span class="route-path">/workspace</span>
-        <span class="route-desc">DeerFlow research workspace</span>
-        <span class="route-arrow">→</span>
-      </a>
-      <a href="/setup"     class="route-row">
-        <span class="route-path">/setup</span>
-        <span class="route-desc">Admin account creation (first boot)</span>
-        <span class="route-arrow">→</span>
-      </a>
-      <a href="/api/health" class="route-row">
-        <span class="route-path">/api/health</span>
-        <span class="route-desc">Backend health check (JSON)</span>
-        <span class="route-arrow">→</span>
-      </a>
-      <a href="/docs"      class="route-row">
-        <span class="route-path">/docs</span>
-        <span class="route-desc">Swagger API reference</span>
-        <span class="route-arrow">→</span>
-      </a>
-    </div>
-
-    <p class="footer">
-      <a href="https://github.com/somratpro/HuggingFlow" target="_blank" rel="noopener">HuggingFlow</a>
-      · MIT License ·
-      <a href="https://github.com/bytedance/deer-flow" target="_blank" rel="noopener">DeerFlow by ByteDance</a>
-    </p>
-  </div>
-</body>
-</html>

docker-compose.yml

@@ -0,0 +1,71 @@
+version: '3.8'
+
+# HuggingFlow — local development
+# Usage:
+#   cp .env.example .env        # fill in LLM_MODEL, LLM_API_KEY, etc.
+#   docker-compose up --build
+
+services:
+  huggingflow:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: huggingflow
+    environment:
+      # ── Required ────────────────────────────────────────────────
+      LLM_MODEL:   ${LLM_MODEL:-openai/gpt-4o}
+      LLM_API_KEY: ${LLM_API_KEY:-}
+
+      # ── Search (optional) ────────────────────────────────────────
+      SERPER_API_KEY: ${SERPER_API_KEY:-}
+      TAVILY_API_KEY: ${TAVILY_API_KEY:-}
+      JINA_API_KEY:   ${JINA_API_KEY:-}
+
+      # ── Auth ─────────────────────────────────────────────────────
+      AUTH_JWT_SECRET: ${AUTH_JWT_SECRET:-dev-secret-change-in-production}
+
+      # ── HF Dataset backup (optional) ─────────────────────────────
+      HF_TOKEN:            ${HF_TOKEN:-}
+      HF_USERNAME:         ${HF_USERNAME:-}
+      BACKUP_DATASET_NAME: ${BACKUP_DATASET_NAME:-huggingflow-backup}
+      SYNC_INTERVAL:       ${SYNC_INTERVAL:-600}
+
+      # ── Custom LLM endpoint (optional) ───────────────────────────
+      CUSTOM_BASE_URL: ${CUSTOM_BASE_URL:-}
+
+      # ── Cloudflare (optional) ─────────────────────────────────────
+      CLOUDFLARE_WORKERS_TOKEN: ${CLOUDFLARE_WORKERS_TOKEN:-}
+      CLOUDFLARE_PROXY_URL:     ${CLOUDFLARE_PROXY_URL:-}
+
+      # ── Timeouts ─────────────────────────────────────────────────
+      BACKEND_READY_TIMEOUT:  ${BACKEND_READY_TIMEOUT:-120}
+      FRONTEND_READY_TIMEOUT: ${FRONTEND_READY_TIMEOUT:-120}
+
+      # ── Privacy ──────────────────────────────────────────────────
+      DO_NOT_TRACK: "1"
+
+    ports:
+      - "7860:7860"    # Public: status dashboard + reverse proxy
+
+    volumes:
+      # Persist data between docker-compose up/down cycles
+      - huggingflow_data:/app/data
+
+      # Hot-reload orchestration scripts (no rebuild needed)
+      - ./start.sh:/app/start.sh
+      - ./health-server.js:/app/health-server.js
+      - ./deerflow-sync.py:/app/deerflow-sync.py
+      - ./nginx.conf:/etc/nginx/nginx.conf
+
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:7860/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 90s
+
+    restart: unless-stopped
+
+volumes:
+  huggingflow_data:
+    driver: local

health-server.js

@@ -136,9 +136,9 @@ function renderDashboard({ backendUp, frontendUp, uptimeHuman, sync, keepalive }
   return `<!doctype html>
 <html lang="en">
 <head>
-  <meta charset="utf-8"/>
-  <meta name="viewport" content="width=device-width,initial-scale=1"/>
-  <meta http-equiv="refresh" content="30"/>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width,initial-scale=1" />
+  <meta http-equiv="refresh" content="30" />
   <title>HuggingFlow Dashboard</title>
   <style>
     :root{color-scheme:dark;--bg:#080c10;--panel:#0e1218;--line:#1e2530;--text:#eef2f7;--muted:#6b7a8d;--soft:#a8b5c4;--good:#22c55e;--warn:#f59e0b;--bad:#f43f5e;--accent:#3b82f6}
@@ -199,7 +199,7 @@ function renderDashboard({ backendUp, frontendUp, uptimeHuman, sync, keepalive }
   });
 </script>
 </body>
-</html>`.replace(/\$\{appOnline\}/g, appOnline ? "true" : "false");  // avoid template literal collision
+</html>`;
 }
 
 // ── Request handler ────────────────────────────────────────────────────────