Update README.md
Browse files
README.md
CHANGED
|
@@ -16,195 +16,3 @@ secrets:
|
|
| 16 |
description: Cloudflare API token for automatic Worker proxy and KeepAlive setup.
|
| 17 |
---
|
| 18 |
|
| 19 |
-
<!-- Badges -->
|
| 20 |
-
[](https://github.com/somratpro/hugging8n)
|
| 21 |
-
[](https://opensource.org/licenses/MIT)
|
| 22 |
-
[](https://huggingface.co/spaces)
|
| 23 |
-
[](https://n8n.io)
|
| 24 |
-
|
| 25 |
-
**Self-hosted n8n workflow automation — free, no server needed.** Hugging8n runs [n8n](https://n8n.io) on HuggingFace Spaces, providing a 24/7 automation engine for your workflows. It includes a premium management dashboard, automatic persistent backup to HF Datasets, and built-in connectivity fixes to bypass platform restrictions. Deploy in minutes on the free HF Spaces tier with full data persistence.
|
| 26 |
-
|
| 27 |
-
## Table of Contents
|
| 28 |
-
|
| 29 |
-
- [✨ Features](#-features)
|
| 30 |
-
- [🎥 Video Tutorial](#-video-tutorial)
|
| 31 |
-
- [🚀 Quick Start](#-quick-start)
|
| 32 |
-
- [🌐 Cloudflare Proxy Setup](#-cloudflare-proxy-setup)
|
| 33 |
-
- [💾 Persistent Backup](#-persistent-backup)
|
| 34 |
-
- [💓 Staying Alive](#-staying-alive)
|
| 35 |
-
- [🔐 Security & Advanced *(Optional)*](#-security--advanced-optional)
|
| 36 |
-
- [💻 Local Development](#-local-development)
|
| 37 |
-
- [🏗️ Architecture](#-architecture)
|
| 38 |
-
- [🐛 Troubleshooting](#-troubleshooting)
|
| 39 |
-
- [📚 Links](#-links)
|
| 40 |
-
- [🤝 Contributing](#-contributing)
|
| 41 |
-
- [📄 License](#-license)
|
| 42 |
-
|
| 43 |
-
## ✨ Features
|
| 44 |
-
|
| 45 |
-
- ⚡ **Zero Config:** Duplicate this Space, set `HF_TOKEN`, and start automating – no other setup needed.
|
| 46 |
-
- 💾 **Persistent Backup:** Workflows, credentials, and settings automatically sync to a private HF Dataset, preserving your data across restarts.
|
| 47 |
-
- 🔐 **Secure by Default:** Uses n8n's native user management and restricted file permissions (`umask 0077`).
|
| 48 |
-
- 🌐 **Built-in Connectivity:** Includes transparent outbound proxying via Cloudflare Workers for Telegram, WhatsApp-related APIs, Google APIs, Discord, and other external services.
|
| 49 |
-
- 📊 **Premium Dashboard:** Beautiful Web UI at `/` for real-time monitoring of uptime, sync health, and n8n status.
|
| 50 |
-
- ⏰ **Easy Keep-Alive:** Uses `CLOUDFLARE_WORKERS_TOKEN` to automatically set up a cron-triggered keep-awake worker at boot.
|
| 51 |
-
- 🐳 **Optimized Infrastructure:** Minimal resource usage with clean startup logs and production-ready proxying.
|
| 52 |
-
|
| 53 |
-
## 🎥 Video Tutorial
|
| 54 |
-
|
| 55 |
-
Watch a quick walkthrough on YouTube: [Deploying Hugging8n on HF Spaces](https://youtu.be/cfMruo5dlF8?si=elM6Mnmh0oQIyxp2).
|
| 56 |
-
|
| 57 |
-
## 🚀 Quick Start
|
| 58 |
-
|
| 59 |
-
### Step 1: Duplicate this Space
|
| 60 |
-
|
| 61 |
-
[](https://huggingface.co/spaces/somratpro/Hugging8n?duplicate=true)
|
| 62 |
-
|
| 63 |
-
### Step 2: Add Your Secrets
|
| 64 |
-
|
| 65 |
-
Navigate to your new Space's **Settings**, scroll down to **Variables and secrets**, and add:
|
| 66 |
-
|
| 67 |
-
- `HF_TOKEN` – Your HuggingFace token with **Write** access (for automatic backup).
|
| 68 |
-
- `CLOUDFLARE_WORKERS_TOKEN` – **(Highly Recommended)** Cloudflare API token. Hugging8n will automatically create and configure a Worker proxy for you.
|
| 69 |
-
|
| 70 |
-
### Step 3: Deploy & Initialize
|
| 71 |
-
|
| 72 |
-
The Space will build and start automatically. Once ready:
|
| 73 |
-
|
| 74 |
-
1. Visit the Space URL.
|
| 75 |
-
2. Click **Open n8n Editor**.
|
| 76 |
-
3. Create your **Owner account** (this is your primary login).
|
| 77 |
-
|
| 78 |
-
### Step 4: Monitor & Manage
|
| 79 |
-
|
| 80 |
-
Use the built-in dashboard at the root URL (`/`) to track:
|
| 81 |
-
|
| 82 |
-
- **Uptime:** Real-time uptime monitoring.
|
| 83 |
-
- **Sync Status:** Visual indicators for your workflow backups.
|
| 84 |
-
- **Keep-Alive:** Setup tool for external monitors.
|
| 85 |
-
|
| 86 |
-
## 🌐 Cloudflare Proxy Setup
|
| 87 |
-
|
| 88 |
-
Hugging Face Free Tier often restricts outbound connections to services like Telegram, Discord, and WhatsApp. Hugging8n solves this with a **Transparent Outbound Proxy** via Cloudflare Workers.
|
| 89 |
-
|
| 90 |
-
### ⚡ Automatic Setup (Recommended)
|
| 91 |
-
|
| 92 |
-
This is the easiest way. Hugging8n will handle the deployment for you.
|
| 93 |
-
|
| 94 |
-
1. Create a **Cloudflare API Token**:
|
| 95 |
-
- Go to [API Tokens](https://dash.cloudflare.com/profile/api-tokens).
|
| 96 |
-
- Create Token -> **Edit Cloudflare Workers** template.
|
| 97 |
-
- Ensure it has `Account: Workers Scripts: Edit` permissions.
|
| 98 |
-
2. Add the token as a secret named `CLOUDFLARE_WORKERS_TOKEN` in your Space Settings.
|
| 99 |
-
|
| 100 |
-
**What happens next?**
|
| 101 |
-
|
| 102 |
-
- Hugging8n automatically creates a Worker named after your Space.
|
| 103 |
-
- It generates a secure, private `CLOUDFLARE_PROXY_SECRET`.
|
| 104 |
-
- All restricted outbound traffic is automatically routed through this Worker.
|
| 105 |
-
|
| 106 |
-
## 💾 Persistent Backup
|
| 107 |
-
|
| 108 |
-
Hugging8n automatically creates a private dataset named `hugging8n-backup` in your Hugging Face account.
|
| 109 |
-
|
| 110 |
-
- **Restore:** On startup, it pulls the latest state from your dataset.
|
| 111 |
-
- **Sync:** Periodically (every 3 minutes by default), it pushes updates to the dataset.
|
| 112 |
-
- **Status:** View current sync health on the Hugging8n Dashboard.
|
| 113 |
-
|
| 114 |
-
| Variable | Default | Description |
|
| 115 |
-
| :--- | :--- | :--- |
|
| 116 |
-
| `SYNC_INTERVAL` | `180` | Backup frequency in seconds |
|
| 117 |
-
|
| 118 |
-
## 💓 Staying Alive *(Recommended on Free HF Spaces)*
|
| 119 |
-
|
| 120 |
-
Your Space will automatically be kept awake by a background Cloudflare Worker when you configure the `CLOUDFLARE_WORKERS_TOKEN` secret. The worker uses a cron trigger to regularly ping your Space's `/health` endpoint. The dashboard displays the current keep-alive worker status.
|
| 121 |
-
|
| 122 |
-
## 🔐 Security & Advanced *(Optional)*
|
| 123 |
-
|
| 124 |
-
Customize your instance with these environment variables:
|
| 125 |
-
|
| 126 |
-
| Variable | Default | Description |
|
| 127 |
-
| :--- | :--- | :--- |
|
| 128 |
-
| `GENERIC_TIMEZONE` | `UTC` | Timezone for your n8n instance |
|
| 129 |
-
| `N8N_LOG_LEVEL` | `error` | Set to `info` or `debug` for more details |
|
| 130 |
-
| `CLOUDFLARE_WORKERS_TOKEN` | — | Cloudflare API token for automatic Worker setup |
|
| 131 |
-
| `CLOUDFLARE_PROXY_DOMAINS` | — | Extra domains to proxy, merged with built-in defaults. Set to `*` to proxy all external traffic. Leave unset to use defaults only. |
|
| 132 |
-
| `CLOUDFLARE_PROXY_SECRET` | — | Optional shared secret for proxy authentication |
|
| 133 |
-
| `CLOUDFLARE_WORKER_NAME` | auto | Custom name for the automatically created Worker |
|
| 134 |
-
| `CLOUDFLARE_ACCOUNT_ID` | auto | Optional Cloudflare account ID override |
|
| 135 |
-
| `SPACE_HOST_OVERRIDE` | — | Override detected host for custom domains |
|
| 136 |
-
| `N8N_STARTUP_TIMEOUT` | `180` | Max seconds to wait for n8n readiness |
|
| 137 |
-
| `CLOUDFLARE_KEEPALIVE_ENABLED` | `true` | Set to `false` to disable the automatic Cloudflare KeepAlive worker |
|
| 138 |
-
|
| 139 |
-
## 💻 Local Development
|
| 140 |
-
|
| 141 |
-
```bash
|
| 142 |
-
git clone https://github.com/somratpro/hugging8n.git
|
| 143 |
-
cd hugging8n
|
| 144 |
-
cp .env.example .env
|
| 145 |
-
# Edit .env with your secrets
|
| 146 |
-
```
|
| 147 |
-
|
| 148 |
-
**With Docker:**
|
| 149 |
-
|
| 150 |
-
```bash
|
| 151 |
-
docker build -t hugging8n .
|
| 152 |
-
docker run -p 7861:7861 --env-file .env hugging8n
|
| 153 |
-
```
|
| 154 |
-
|
| 155 |
-
## 🏗️ Architecture
|
| 156 |
-
|
| 157 |
-
- **Dashboard (`/`)**: Management, monitoring, and keep-alive tools.
|
| 158 |
-
- **n8n Editor (`/home/workflows`)**: All other paths are proxied to the internal n8n instance.
|
| 159 |
-
- **Health Check (`/health`)**: Used for uptime monitoring and readiness probes.
|
| 160 |
-
- **Sync Engine**: Background process managing HF Dataset persistence.
|
| 161 |
-
- **Transparent Proxy**: Intercepts requests to blocked domains and routes them via Cloudflare.
|
| 162 |
-
|
| 163 |
-
## 🐛 Troubleshooting
|
| 164 |
-
|
| 165 |
-
- **Telegram/Google/WhatsApp not connecting:** Ensure `CLOUDFLARE_WORKERS_TOKEN` or `CLOUDFLARE_PROXY_URL` is set. Use `CLOUDFLARE_PROXY_DOMAINS=*` to proxy all external traffic.
|
| 166 |
-
- **Workflows not saving:** Check if `HF_TOKEN` has **Write** access to your account.
|
| 167 |
-
- **Space keeps sleeping:** Add `CLOUDFLARE_WORKERS_TOKEN` as a Space secret to enable automatic keep-awake monitoring via Cloudflare Workers.
|
| 168 |
-
- **Authentication errors:** n8n v2 uses its own internal users; ensure you created the owner account on first run.
|
| 169 |
-
|
| 170 |
-
## 🌟 More Projects
|
| 171 |
-
|
| 172 |
-
Similar projects by [@somratpro](https://github.com/somratpro) — all free, one-click deploy on HF Spaces:
|
| 173 |
-
|
| 174 |
-
| Project | What it runs | HF Space | GitHub |
|
| 175 |
-
| :--- | :--- | :--- | :--- |
|
| 176 |
-
| **HuggingFlow** | DeerFlow — deep research agent | [Space](https://huggingface.co/spaces/somratpro/HuggingFlow) | [Repo](https://github.com/somratpro/HuggingFlow) |
|
| 177 |
-
| **HuggingMes** | Hermes — Self-hosted agent gateway | [Space](https://huggingface.co/spaces/somratpro/HuggingMes) | [Repo](https://github.com/somratpro/huggingmes) |
|
| 178 |
-
| **HuggingClaw** | OpenClaw — Claude Code in the browser | [Space](https://huggingface.co/spaces/somratpro/HuggingClaw) | [Repo](https://github.com/somratpro/huggingclaw) |
|
| 179 |
-
| **HuggingClip** | Paperclip — AI agent orchestration platform | [Space](https://huggingface.co/spaces/somratpro/HuggingClip) | [Repo](https://github.com/somratpro/huggingclip) |
|
| 180 |
-
| **HuggingPost** | Postiz — social media scheduler | [Space](https://huggingface.co/spaces/somratpro/HuggingPost) | [Repo](https://github.com/somratpro/HuggingPost) |
|
| 181 |
-
|
| 182 |
-
## 📚 Links
|
| 183 |
-
|
| 184 |
-
- [n8n Documentation](https://docs.n8n.io)
|
| 185 |
-
- [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces)
|
| 186 |
-
- [Cloudflare Workers](https://workers.cloudflare.com/)
|
| 187 |
-
|
| 188 |
-
## ❤️ Support
|
| 189 |
-
|
| 190 |
-
If Hugging8n saves you time, consider buying me a coffee to keep the projects alive!
|
| 191 |
-
|
| 192 |
-
**USDT (TRC-20 / TRON network only)**
|
| 193 |
-
|
| 194 |
-
```
|
| 195 |
-
TELx8TJz1W1h7n6SgpgGNNGZXpJCEUZrdB
|
| 196 |
-
```
|
| 197 |
-
|
| 198 |
-
> [!WARNING]
|
| 199 |
-
> Send **USDT on TRC-20 network only**. Sending other tokens or using a different network will result in permanent loss.
|
| 200 |
-
|
| 201 |
-
## 🤝 Contributing
|
| 202 |
-
|
| 203 |
-
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
| 204 |
-
|
| 205 |
-
## 📄 License
|
| 206 |
-
|
| 207 |
-
MIT — see [LICENSE](LICENSE) for details.
|
| 208 |
-
|
| 209 |
-
---
|
| 210 |
-
*Made with ❤️ by [@somratpro](https://github.com/somratpro)*
|
|
|
|
| 16 |
description: Cloudflare API token for automatic Worker proxy and KeepAlive setup.
|
| 17 |
---
|
| 18 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|