FincH12 commited on
Commit
2e2946a
·
verified ·
1 Parent(s): 36eefaf

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +0 -192
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
- [![GitHub Stars](https://img.shields.io/github/stars/somratpro/hugging8n?style=flat-square)](https://github.com/somratpro/hugging8n)
21
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
22
- [![HF Space](https://img.shields.io/badge/🤗%20HuggingFace-Space-blue?style=flat-square)](https://huggingface.co/spaces)
23
- [![n8n](https://img.shields.io/badge/n8n-Workflow-orange?style=flat-square)](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
- [![Duplicate this Space](https://huggingface.co/datasets/huggingface/badges/resolve/main/duplicate-this-space-xl.svg)](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