Calvinho98/SOP-n8n-coreV3

N8n Free

This repository deploys n8n on Hugging Face Spaces with a Supabase Postgres backend. It ships with GitHub Actions to keep the Space alive, run health checks, and update n8n.

Quick start

• —Fork this repo on GitHub.
• —Create a Supabase project and run the keep-alive SQL.
• —Create a Hugging Face Space (Docker) linked to your fork.
• —Add Hugging Face Space secrets and variables (tables below).
• —Add GitHub Actions secrets and variables (tables below).
• —Update the Space remote in workflows and the local healthcheck script.
• —Trigger the push or update workflow once.

Deployment guide (Hugging Face Spaces only)

1. Fork the repository

Fork this repo to your GitHub account.

2. Create a Supabase project

1. 1.Create a new project at Supabase.
2. 2.In SQL Editor, run:

CREATE TABLE "keep-alive" (
  id BIGINT generated BY DEFAULT AS IDENTITY,
  name text NULL,
  created_at timestamptz DEFAULT now(),
  CONSTRAINT "keep-alive_pkey" PRIMARY KEY (id)
);
INSERT INTO "keep-alive"(name) VALUES ('ping');

1. 1.Enable SSL in Project Settings > Database > SSL Configuration.
2. 2.Collect database connection details from Project Settings > Database: host, port, database user, password, and database name.

3. Create a Hugging Face Space (Docker)

1. 1.Create a new Space and choose Docker as the SDK.
2. 2.Link it to your forked GitHub repository.
3. 3.Pick a free hardware option.

4. Configure Hugging Face Space secrets

Add these as Secrets in the Space settings:

5. Configure Hugging Face Space variables

Add these as Variables in the Space settings:

Optional execution retention settings:

6. Configure GitHub Actions secrets and variables

Add these in your forked repo under Settings > Secrets and variables > Actions.

Secrets:

Variables:

7. Confirm HF_REPO is set

HF_REPO is used to build the Hugging Face Space git remote. Make sure the Actions variable is set to owner/space for your fork.

Operations and automation

Update n8n version

Run the update-n8n.yml workflow manually. The scheduled trigger is commented out; uncomment it if you want automatic updates. It:

1. 1.Checks the latest stable n8n version tag via GitHub releases/latest API (pre-releases are excluded).
2. 2.Checks version-blocklist.txt (currently includes 2.10.0).
3. 3.Updates the Dockerfile tag only when the latest version is not blacklisted.
4. 4.Commits the change.
5. 5.Pushes to the Hugging Face Space.

To block additional versions, edit version-blocklist.txt and add one version per line.

Push to Hugging Face on every commit

push-to-huggingface.yml pushes main to your Space whenever you push to GitHub.

Keep-alive workflows

• —huggingface-keep-alive.yml pings your Space URL.
• —supabase-keep-alive.yml pings the keep-alive table via REST. Both schedules are commented out by default; uncomment them to enable cron.

Health checks and rebuilds

healthcheck.yml runs every 10 minutes and calls healthcheck-rebuild.sh. It checks https://<owner>-<space>.hf.space/healthz/readiness (derived from HF_REPO) and forces a rebuild if unhealthy.

To run locally:

HF_REPO=<owner>/<space> \
HF_TOKEN=<your_hf_token> \
bash healthcheck-rebuild.sh

Optional Telegram alerts:

TG_TOKEN=<bot_token> TG_CHAT_ID=<chat_id>

Optional n8n workflow

Import Auto keep n8n alive and updates on n8n-free repo.json into n8n if you want an in-app workflow for keep-alive and update triggers.

Troubleshooting

• —Healthcheck fails with missing HF_REPO: Set HF_REPO in GitHub repo variables using owner/space format.
• —Database SSL errors: Ensure SSL is enabled in Supabase and DB_POSTGRESDB_SSL_CA contains the full PEM certificate.
• —Webhooks point to the wrong host: Align N8N_HOST, N8N_EDITOR_BASE_URL, and WEBHOOK_URL to the Space host.

Security notes

Do not commit secrets. Use Hugging Face Space secrets and GitHub Actions secrets.