initial commit

Dockerfile

@@ -0,0 +1,38 @@
+FROM node:22-slim
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    N8N_PORT=5678 \
+    HF_HUB_DISABLE_PROGRESS_BARS=1 \
+    PYTHONUNBUFFERED=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl \
+    git \
+    jq \
+    python3 \
+    python3-pip \
+    sqlite3 \
+    tini \
+    && pip3 install --no-cache-dir --break-system-packages huggingface_hub==0.34.4 \
+    && npm install -g n8n@latest \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN mkdir -p /home/node/app /home/node/.n8n && \
+    chown -R node:node /home/node
+
+WORKDIR /home/node/app
+
+COPY --chown=node:node health-server.js /home/node/app/health-server.js
+COPY --chown=node:node n8n-sync.py /home/node/app/n8n-sync.py
+COPY --chown=node:node setup-uptimerobot.sh /home/node/app/setup-uptimerobot.sh
+COPY --chown=node:node start.sh /home/node/app/start.sh
+
+RUN chmod +x /home/node/app/start.sh /home/node/app/setup-uptimerobot.sh
+
+USER node
+
+EXPOSE 7861
+
+ENTRYPOINT ["/usr/bin/tini", "--"]
+CMD ["/home/node/app/start.sh"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Somrat Sorkar (@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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,57 @@
+---
+title: Hugging8n
+emoji: "8"
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7861
+pinned: false
+license: mit
+---
+
+# Hugging8n
+
+Run a self-hosted n8n instance on Hugging Face Spaces without external database services.
+
+This Space uses:
+
+- `n8n` running locally on port `5678`
+- a small proxy/health server on port `7861` for HF Spaces
+- periodic backup of `/home/node/.n8n` to a private Hugging Face Dataset
+
+## Required secret
+
+- `HF_TOKEN`: Hugging Face token with write access to create/update a private dataset backup
+
+## Recommended variables
+
+- `BACKUP_DATASET_NAME`: backup dataset name. Default: `hugging8n-backup`
+- `SYNC_INTERVAL`: backup interval in seconds. Default: `180`
+- `GENERIC_TIMEZONE`: timezone for schedule triggers. Example: `Asia/Dhaka`
+- `N8N_ENCRYPTION_KEY`: optional explicit encryption key. If omitted, n8n stores it inside `.n8n` and the backup preserves it
+- `N8N_BASIC_AUTH_ACTIVE`: set to `true` if you want built-in basic auth
+- `N8N_BASIC_AUTH_USER`: basic auth username
+- `N8N_BASIC_AUTH_PASSWORD`: basic auth password
+
+## Optional variables
+
+- `HF_USERNAME`: owner of the backup dataset. By default this is inferred from `SPACE_AUTHOR_NAME`
+- `SPACE_HOST_OVERRIDE`: set this only if you want to override the detected Space hostname
+- `N8N_DIAGNOSTICS_ENABLED=false`
+- `N8N_PERSONALIZATION_ENABLED=false`
+
+## How persistence works
+
+On startup, the Space restores `/home/node/.n8n` from a private dataset repo.
+
+While running, it watches for changes and uploads the updated `.n8n` directory back to the dataset. This preserves:
+
+- workflows
+- credentials
+- users
+- SQLite database
+- encryption key
+
+## Keep-alive
+
+If you already solved the sleep problem in your HF setup, use that. If not, `setup-uptimerobot.sh` can create an external monitor for `https://<your-space>.hf.space/health`.

health-server.js

@@ -0,0 +1,97 @@
+const http = require("http");
+const net = require("net");
+const fs = require("fs");
+
+const PUBLIC_PORT = Number(process.env.PUBLIC_PORT || 7861);
+const TARGET_PORT = Number(process.env.N8N_PORT || 5678);
+const TARGET_HOST = "127.0.0.1";
+const STATUS_FILE = "/tmp/hugging8n-sync-status.json";
+
+function getStatus() {
+  try {
+    return JSON.parse(fs.readFileSync(STATUS_FILE, "utf8"));
+  } catch {
+    return {
+      status: "unknown",
+      message: "No sync status yet",
+      timestamp: new Date().toISOString(),
+    };
+  }
+}
+
+function writeJson(res, statusCode, payload) {
+  res.writeHead(statusCode, { "content-type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(payload));
+}
+
+function buildHeaders(req) {
+  return {
+    ...req.headers,
+    host: req.headers.host || "",
+    "x-forwarded-for": req.socket.remoteAddress || "",
+    "x-forwarded-host": req.headers.host || "",
+    "x-forwarded-proto": req.headers["x-forwarded-proto"] || "https",
+  };
+}
+
+const server = http.createServer((req, res) => {
+  if (req.url === "/health") {
+    return writeJson(res, 200, {
+      ok: true,
+      service: "hugging8n",
+      n8nPort: TARGET_PORT,
+      ...getStatus(),
+    });
+  }
+
+  if (req.url === "/status") {
+    return writeJson(res, 200, getStatus());
+  }
+
+  const upstream = http.request(
+    {
+      hostname: TARGET_HOST,
+      port: TARGET_PORT,
+      path: req.url,
+      method: req.method,
+      headers: buildHeaders(req),
+    },
+    (upstreamRes) => {
+      res.writeHead(upstreamRes.statusCode || 502, upstreamRes.headers);
+      upstreamRes.pipe(res);
+    },
+  );
+
+  upstream.on("error", (error) => {
+    writeJson(res, 502, {
+      ok: false,
+      error: "upstream_unavailable",
+      detail: error.message,
+    });
+  });
+
+  req.pipe(upstream);
+});
+
+server.on("upgrade", (req, socket, head) => {
+  const upstream = net.connect(TARGET_PORT, TARGET_HOST, () => {
+    socket.write(
+      `${req.method} ${req.url} HTTP/${req.httpVersion}\r\n` +
+        Object.entries(buildHeaders(req))
+          .map(([key, value]) => `${key}: ${value}`)
+          .join("\r\n") +
+        "\r\n\r\n",
+    );
+    if (head && head.length) upstream.write(head);
+    upstream.pipe(socket);
+    socket.pipe(upstream);
+  });
+
+  upstream.on("error", () => {
+    socket.destroy();
+  });
+});
+
+server.listen(PUBLIC_PORT, "0.0.0.0", () => {
+  console.log(`Hugging8n proxy listening on ${PUBLIC_PORT}, forwarding to ${TARGET_PORT}`);
+});

n8n-sync.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+
+import hashlib
+import json
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+os.environ.setdefault("HF_HUB_DISABLE_PROGRESS_BARS", "1")
+
+from huggingface_hub import HfApi, snapshot_download, upload_folder
+from huggingface_hub.errors import RepositoryNotFoundError
+
+N8N_HOME = Path(os.environ.get("N8N_USER_FOLDER", "/home/node/.n8n"))
+STATUS_FILE = Path("/tmp/hugging8n-sync-status.json")
+INTERVAL = int(os.environ.get("SYNC_INTERVAL", "180"))
+HF_TOKEN = os.environ.get("HF_TOKEN", "").strip()
+HF_USERNAME = (
+    os.environ.get("HF_USERNAME", "").strip()
+    or os.environ.get("SPACE_AUTHOR_NAME", "").strip()
+)
+BACKUP_DATASET_NAME = os.environ.get("BACKUP_DATASET_NAME", "hugging8n-backup").strip()
+HF_API = HfApi(token=HF_TOKEN) if HF_TOKEN else None
+RUNNING = True
+
+
+def write_status(status: str, message: str) -> None:
+    payload = {
+        "status": status,
+        "message": message,
+        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+    STATUS_FILE.write_text(json.dumps(payload), encoding="utf-8")
+
+
+def dataset_repo_id() -> str:
+    if not HF_USERNAME:
+        raise RuntimeError("HF_USERNAME or SPACE_AUTHOR_NAME is required for backup repo naming")
+    return f"{HF_USERNAME}/{BACKUP_DATASET_NAME}"
+
+
+def ensure_repo_exists() -> str:
+    repo_id = dataset_repo_id()
+    try:
+        HF_API.repo_info(repo_id=repo_id, repo_type="dataset")
+    except RepositoryNotFoundError:
+        HF_API.create_repo(repo_id=repo_id, repo_type="dataset", private=True)
+    return repo_id
+
+
+def fingerprint_dir(root: Path) -> str:
+    hasher = hashlib.sha256()
+    if not root.exists():
+        return hasher.hexdigest()
+
+    for path in sorted(p for p in root.rglob("*") if p.is_file()):
+        rel = path.relative_to(root).as_posix()
+        if rel.startswith(".cache/"):
+            continue
+        hasher.update(rel.encode("utf-8"))
+        with path.open("rb") as handle:
+            for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                hasher.update(chunk)
+    return hasher.hexdigest()
+
+
+def create_snapshot_dir(source_root: Path) -> Path:
+    staging_root = Path(tempfile.mkdtemp(prefix="hugging8n-sync-"))
+    database_path = source_root / "database.sqlite"
+
+    for path in sorted(source_root.rglob("*")):
+        rel = path.relative_to(source_root)
+        rel_posix = rel.as_posix()
+        if rel_posix.startswith(".cache/"):
+            continue
+        target = staging_root / rel
+        if path.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+            continue
+        if rel_posix in {"database.sqlite", "database.sqlite-shm", "database.sqlite-wal"}:
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(path, target)
+
+    if database_path.exists():
+        target_db = staging_root / "database.sqlite"
+        target_db.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            subprocess.run(
+                ["sqlite3", str(database_path), f".backup {target_db}"],
+                check=True,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        except Exception:
+            shutil.copy2(database_path, target_db)
+            for suffix in ("-wal", "-shm"):
+                sidecar = source_root / f"database.sqlite{suffix}"
+                if sidecar.exists():
+                    shutil.copy2(sidecar, staging_root / sidecar.name)
+
+    return staging_root
+
+
+def restore() -> bool:
+    if not HF_TOKEN:
+        write_status("disabled", "HF_TOKEN is not configured.")
+        return False
+
+    repo_id = dataset_repo_id()
+    write_status("restoring", f"Restoring state from {repo_id}")
+
+    try:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            snapshot_download(
+                repo_id=repo_id,
+                repo_type="dataset",
+                token=HF_TOKEN,
+                local_dir=tmpdir,
+                local_dir_use_symlinks=False,
+            )
+
+            tmp_path = Path(tmpdir)
+            if not any(tmp_path.iterdir()):
+                write_status("fresh", "Backup dataset is empty. Starting fresh.")
+                return True
+
+            N8N_HOME.mkdir(parents=True, exist_ok=True)
+            for child in N8N_HOME.iterdir():
+                if child.name == ".cache":
+                    continue
+                if child.is_dir():
+                    shutil.rmtree(child, ignore_errors=True)
+                else:
+                    child.unlink(missing_ok=True)
+
+            for child in tmp_path.iterdir():
+                if child.name == ".cache":
+                    continue
+                destination = N8N_HOME / child.name
+                if child.is_dir():
+                    shutil.copytree(child, destination)
+                else:
+                    shutil.copy2(child, destination)
+
+        write_status("restored", f"Restored state from {repo_id}")
+        return True
+    except RepositoryNotFoundError:
+        write_status("fresh", f"Backup dataset {repo_id} does not exist yet.")
+        return True
+    except Exception as exc:
+        write_status("error", f"Restore failed: {exc}")
+        print(f"Restore failed: {exc}", file=sys.stderr)
+        return False
+
+
+def sync_once(last_fingerprint: str | None = None) -> str:
+    if not HF_TOKEN:
+        write_status("disabled", "HF_TOKEN is not configured.")
+        return last_fingerprint or ""
+
+    repo_id = ensure_repo_exists()
+    current_fingerprint = fingerprint_dir(N8N_HOME)
+    if last_fingerprint is not None and current_fingerprint == last_fingerprint:
+        write_status("idle", "No state changes detected.")
+        return last_fingerprint
+
+    write_status("syncing", f"Uploading state to {repo_id}")
+    snapshot_dir = create_snapshot_dir(N8N_HOME)
+    try:
+        upload_folder(
+            folder_path=str(snapshot_dir),
+            repo_id=repo_id,
+            repo_type="dataset",
+            token=HF_TOKEN,
+            commit_message=f"Hugging8n sync {time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())}",
+            ignore_patterns=[".cache/*"],
+        )
+    finally:
+        shutil.rmtree(snapshot_dir, ignore_errors=True)
+    write_status("success", f"Uploaded state to {repo_id}")
+    return current_fingerprint
+
+
+def handle_signal(_sig, _frame) -> None:
+    global RUNNING
+    RUNNING = False
+
+
+def loop() -> int:
+    signal.signal(signal.SIGTERM, handle_signal)
+    signal.signal(signal.SIGINT, handle_signal)
+
+    last_fingerprint = fingerprint_dir(N8N_HOME)
+    write_status("configured", f"Backup loop active with {INTERVAL}s interval.")
+
+    while RUNNING:
+        try:
+            last_fingerprint = sync_once(last_fingerprint)
+        except Exception as exc:
+            write_status("error", f"Sync failed: {exc}")
+            print(f"Sync failed: {exc}", file=sys.stderr)
+        for _ in range(INTERVAL):
+            if not RUNNING:
+                break
+            time.sleep(1)
+
+    try:
+        sync_once(None)
+    except Exception as exc:
+        write_status("error", f"Final sync failed: {exc}")
+        print(f"Final sync failed: {exc}", file=sys.stderr)
+    return 0
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("Usage: n8n-sync.py [restore|sync-once|loop]", file=sys.stderr)
+        return 1
+
+    command = sys.argv[1]
+    if command == "restore":
+        return 0 if restore() else 1
+    if command == "sync-once":
+        sync_once(None)
+        return 0
+    if command == "loop":
+        return loop()
+
+    print(f"Unknown command: {command}", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

setup-uptimerobot.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+set -euo pipefail
+
+API_URL="https://api.uptimerobot.com/v2"
+API_KEY="${UPTIMEROBOT_API_KEY:-}"
+SPACE_HOST_INPUT="${1:-${SPACE_HOST:-}}"
+
+if [ -z "$API_KEY" ]; then
+  echo "Missing UPTIMEROBOT_API_KEY."
+  exit 1
+fi
+
+if [ -z "$SPACE_HOST_INPUT" ]; then
+  echo "Missing Space host."
+  echo "Usage: UPTIMEROBOT_API_KEY=... ./setup-uptimerobot.sh your-space.hf.space"
+  exit 1
+fi
+
+SPACE_HOST_CLEAN="${SPACE_HOST_INPUT#https://}"
+SPACE_HOST_CLEAN="${SPACE_HOST_CLEAN#http://}"
+SPACE_HOST_CLEAN="${SPACE_HOST_CLEAN%%/*}"
+
+MONITOR_URL="https://${SPACE_HOST_CLEAN}/health"
+MONITOR_NAME="${UPTIMEROBOT_MONITOR_NAME:-Hugging8n ${SPACE_HOST_CLEAN}}"
+INTERVAL="${UPTIMEROBOT_INTERVAL:-5}"
+
+MONITORS_RESPONSE=$(curl -sS -X POST "${API_URL}/getMonitors" \
+  -d "api_key=${API_KEY}" \
+  -d "format=json" \
+  -d "logs=0" \
+  -d "response_times=0" \
+  -d "response_times_limit=1")
+
+MONITOR_ID=$(printf '%s' "$MONITORS_RESPONSE" | jq -r --arg url "$MONITOR_URL" '
+  (.monitors // []) | map(select(.url == $url)) | first | .id // empty
+')
+
+if [ -n "$MONITOR_ID" ]; then
+  echo "Monitor already exists (id=${MONITOR_ID}) for ${MONITOR_URL}"
+  exit 0
+fi
+
+CURL_ARGS=(
+  -sS
+  -X POST "${API_URL}/newMonitor"
+  -d "api_key=${API_KEY}"
+  -d "format=json"
+  -d "type=1"
+  -d "friendly_name=${MONITOR_NAME}"
+  -d "url=${MONITOR_URL}"
+  -d "interval=${INTERVAL}"
+)
+
+if [ -n "${UPTIMEROBOT_ALERT_CONTACTS:-}" ]; then
+  CURL_ARGS+=(-d "alert_contacts=${UPTIMEROBOT_ALERT_CONTACTS}")
+fi
+
+CREATE_RESPONSE=$(curl "${CURL_ARGS[@]}")
+CREATE_STATUS=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.stat // "fail"')
+
+if [ "$CREATE_STATUS" != "ok" ]; then
+  printf '%s\n' "$CREATE_RESPONSE"
+  exit 1
+fi
+
+NEW_ID=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.monitor.id // empty')
+echo "Created UptimeRobot monitor ${NEW_ID:-"(id unavailable)"} for ${MONITOR_URL}"

start.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+set -euo pipefail
+
+APP_DIR="/home/node/app"
+N8N_HOME="/home/node/.n8n"
+N8N_PORT="${N8N_PORT:-5678}"
+PUBLIC_PORT="${PUBLIC_PORT:-7861}"
+SYNC_INTERVAL="${SYNC_INTERVAL:-180}"
+
+mkdir -p "$N8N_HOME"
+
+SPACE_HOST_DETECTED="${SPACE_HOST_OVERRIDE:-${SPACE_HOST:-}}"
+if [ -n "$SPACE_HOST_DETECTED" ]; then
+  export N8N_HOST="${N8N_HOST:-$SPACE_HOST_DETECTED}"
+  export WEBHOOK_URL="${WEBHOOK_URL:-https://${SPACE_HOST_DETECTED}/}"
+  export N8N_EDITOR_BASE_URL="${N8N_EDITOR_BASE_URL:-https://${SPACE_HOST_DETECTED}/}"
+fi
+
+export N8N_PORT
+export N8N_PROTOCOL="${N8N_PROTOCOL:-https}"
+export N8N_PROXY_HOPS="${N8N_PROXY_HOPS:-1}"
+export N8N_LISTEN_ADDRESS="${N8N_LISTEN_ADDRESS:-0.0.0.0}"
+export N8N_SECURE_COOKIE="${N8N_SECURE_COOKIE:-true}"
+export N8N_DIAGNOSTICS_ENABLED="${N8N_DIAGNOSTICS_ENABLED:-false}"
+export N8N_PERSONALIZATION_ENABLED="${N8N_PERSONALIZATION_ENABLED:-false}"
+export N8N_USER_FOLDER="$N8N_HOME"
+export N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS="${N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS:-true}"
+export GENERIC_TIMEZONE="${GENERIC_TIMEZONE:-${TZ:-UTC}}"
+export TZ="${TZ:-$GENERIC_TIMEZONE}"
+
+echo ""
+echo "  ╔════════════════════════════════════╗"
+echo "  ║            Hugging8n              ║"
+echo "  ╚════════════════════════════════════╝"
+echo ""
+echo "Public host : ${SPACE_HOST_DETECTED:-not detected}"
+echo "n8n port    : ${N8N_PORT}"
+echo "Public port : ${PUBLIC_PORT}"
+echo "Timezone    : ${GENERIC_TIMEZONE}"
+echo "Sync every  : ${SYNC_INTERVAL}s"
+
+if [ -n "${HF_TOKEN:-}" ]; then
+  echo "Restoring persisted n8n state from HF Dataset..."
+  python3 "$APP_DIR/n8n-sync.py" restore || true
+else
+  echo "HF_TOKEN is not set. Running without dataset persistence."
+fi
+
+cleanup() {
+  echo "Stopping Hugging8n..."
+  if [ -n "${SYNC_PID:-}" ] && kill -0 "$SYNC_PID" 2>/dev/null; then
+    kill "$SYNC_PID" 2>/dev/null || true
+  fi
+  if [ -n "${N8N_PID:-}" ] && kill -0 "$N8N_PID" 2>/dev/null; then
+    kill "$N8N_PID" 2>/dev/null || true
+  fi
+  if [ -n "${PROXY_PID:-}" ] && kill -0 "$PROXY_PID" 2>/dev/null; then
+    kill "$PROXY_PID" 2>/dev/null || true
+  fi
+  if [ -n "${HF_TOKEN:-}" ]; then
+    echo "Running final backup pass..."
+    python3 "$APP_DIR/n8n-sync.py" sync-once || true
+  fi
+}
+
+trap cleanup EXIT INT TERM
+
+if [ -n "${HF_TOKEN:-}" ]; then
+  python3 "$APP_DIR/n8n-sync.py" loop &
+  SYNC_PID=$!
+fi
+
+node "$APP_DIR/health-server.js" &
+PROXY_PID=$!
+
+n8n start &
+N8N_PID=$!
+
+wait "$N8N_PID"