xfirepc

n8n-octopus

<p align="center"> <img src="assets/Logofn.png" alt="Octopus Logo" width="200" /> </p> <h1 align="center">Octopus</h1> <p align="center"> <strong>Orchestration system for managing multiple <a href="https://n8n.io/">N8N</a> workflow automation instances on a single server.</strong><br> Shared PostgreSQL, shared Redis, centralized Nginx reverse proxy with automatic SSL — all from a web panel. </p> <p align="center"> <img src="https://img.shields.io/badge/license-MIT-blue" alt="License" /> <img src="https://img.shields.io/badge/node-%3E%3D18-green" alt="Node" /> <img src="https://img.shields.io/badge/platform-Ubuntu-orange" alt="Platform" /> </p> --- ## Features - **Automatic SSL Domains** — Self-signed or Let's Encrypt certificates generated per instance. Auto-renewal via cron. Point your DNS, create the instance, HTTPS just works. - **One-Click Backup & Restore** — Manual or scheduled backups (cron expressions). Restore any instance to a previous state with a single click. Automatic cleanup of old backups. - **Real-Time SQL Editor** — Query any database directly from the browser. Pagination, syntax highlighting, and confirmation for destructive queries (DROP/DELETE/TRUNCATE). - **Shared Redis & PostgreSQL** — All instances share a single PostgreSQL 16 and Redis 7 cluster. Each instance gets its own isolated database — zero per-instance DB overhead. - **Vector Database for RAG Systems** — PostgreSQL with pgvector support enables vector storage and similarity search, ready for AI/RAG workflows directly within N8N instances. - **Template System** — Save instance configurations as reusable templates. Import SQL templates to bootstrap databases. Spin up pre-configured instances in seconds. - **Worker Scalability** — Each instance can run dedicated workers for background execution. Scale workflow processing independently of the main instance. - **On-Demand Resource Optimization** — Set CPU and memory limits per instance. Start and stop instances as needed — idle instances consume zero resources. --- ## Tech Stack | Layer | Technology | |-------|-----------| | **Frontend** | React 18, Vite, TailwindCSS, ShadCN UI (Radix), Axios | | **Backend** | Node.js 18+, Express.js, ES Modules | | **Database** | PostgreSQL 16 Alpine (Docker container) | | **Cache/Queue** | Redis 7 Alpine (Docker container) | | **Proxy** | Nginx (Docker container), ports 80/443 | | **Containers** | Docker CE, dockerode, execa | | **Process** | PM2 (production), Vite dev server (development) | | **SSL** | OpenSSL (self-signed), Certbot (Let's Encrypt) | | **Auth** | API Key (header `x-api-key` or cookie `auth_key`) | --- ## Architecture ``` Internet | ┌─────┴─────┐ │ Nginx │ :80 / :443 │ Proxy │ n8nmanager-proxy └─────┬─────┘ │ n8nmanager-network (Docker bridge) ┌────────────────┼────────────────┐ │ │ │ ┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐ │ instance_1 │ │ instance_2 │ │ instance_N │ │ + worker_1 │ │ + worker_2 │ │ + worker_N │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ └────────────────┼────────────────┘ │ ┌────────────┼────────────┐ │ │ ┌──────┴──────┐ ┌───────┴─────┐ │ PostgreSQL │ │ Redis │ │ :5432 │ │ :6379 │ └─────────────┘ └─────────────┘ n8nmanager-database n8nmanager-redis ``` All containers run on the `n8nmanager-network` bridge network. The Nginx proxy routes each domain to its corresponding N8N instance. --- ## Quick Start (Production) ### Requirements - **Ubuntu** 20.04 / 22.04 / 24.04 - **1 GB RAM** minimum (2 GB+ recommended) - **Root access** (`sudo`) - **Domain** pointing to the server IP (for Let's Encrypt SSL) ### Automatic Installer ```bash git clone https://github.com/SpiderCode-dev/n8n-octopus.git cd n8n-octopus sudo ./install.sh ``` The installer is interactive and handles everything in 9 steps: | Step | What it does | |------|-------------| | 1 | Verifies Ubuntu with internet connectivity | | 2 | Prompts for: system user, ports, panel domain, DB credentials, SSL type | | 3 | Installs Docker CE, curl, git, build-essential, openssl, certbot, ufw | | 4 | Creates system user, installs NVM + Node.js 18 + pnpm + PM2 | | 5 | Copies the project, generates `.env` for backend and frontend, installs deps, builds | | 6 | Configures PM2 for backend and frontend with auto-start on boot | | 7 | Calls the API to create the Docker network, PostgreSQL/Redis/Nginx containers and panel SSL | | 8 | Configures UFW (firewall): SSH, 80, and 443 only. Adds Let's Encrypt cron renewal if selected | | 9 | Displays URLs, API Key, and useful commands | When finished, the panel is available at `https://your-domain.com`. --- ## Manual Setup (Development) ### Requirements - Node.js 18+ with pnpm - Docker and Docker Compose - Git ### Steps ```bash # 1. Clone git clone https://github.com/SpiderCode-dev/n8n-octopus.git cd n8n-octopus # 2. Install dependencies pnpm install:all # 3. Configure backend cp app/backend/.env.example app/backend/.env # Edit app/backend/.env with your credentials (see Environment Variables section) # 4. Start in development mode pnpm dev ``` This starts the backend at `http://localhost:3000` and the frontend at `http://localhost:5173`. Vite automatically proxies `/api` to the backend. --- ## Environment Variables ### Backend (`app/backend/.env`) | Variable | Description | Example | |----------|------------|---------| | `AUTH_KEY` | API authentication key | `openssl rand -hex 32` | | `POSTGRES_USER` | Shared PostgreSQL user | `octopus` | | `POSTGRES_PASSWORD` | PostgreSQL password | (secure) | | `REDIS_PASSWORD` | Redis password | (secure) | | `PORT` | Backend port | `3000` | | `WORK_PATH` | Base directory for data, sites, configs | `/home/octopus/n8n-manager` | | `SITES_PATH` | Instances subdirectory (relative to WORK_PATH) | `sites` | | `FRONTEND_URL` | Frontend URL (for CORS) | `https://panel.example.com` | | `FRONTEND_SERVER_URL` | Alternative frontend URL (public IP) | `http://1.2.3.4:8080` | | `PUID` / `PGID` | UID/GID for containers | `1000` | | `WORK_HOST` | `local` or remote host IP (SFTP) | `local` | ### Frontend (`app/frontend/.env`) | Variable | Description | Example | |----------|------------|---------| | `VITE_BACKEND_URL` | Backend base URL (optional, defaults to `/api`) | `https://panel.example.com` | --- ## Domain Configuration ### How Routing Works Octopus uses a centralized Nginx proxy (container `n8nmanager-proxy`) listening on ports 80 and 443. When you create an N8N instance with a domain, Octopus: 1. Auto-generates the Nginx configuration for that domain 2. If SSL is selected, generates the certificate (self-signed or Let's Encrypt) 3. Reloads Nginx to activate the new route ### Connecting a Domain to an Instance **1. Configure DNS** — In your domain provider, create an A record: ``` Type: A Name: my-instance (or @ for the root domain) Value: YOUR_SERVER_IP TTL: 300 ``` **2. Create the instance in Octopus** — From the web panel: - Go to **Instances** > **Create Instance** - Enter the name and domain (`my-instance.example.com`) - Select SSL mode: - **None** — HTTP only (port 80) - **Self-signed** — HTTPS with self-signed certificate (development/internal) - **Let's Encrypt** — HTTPS with valid certificate (requires DNS already pointing to the server) **3. Done** — The N8N instance is available at `https://my-instance.example.com`. ### Octopus Panel Domain The admin panel also runs behind Nginx. It is configured during installation or manually from **Nginx** > **System Configuration** in the panel. ### Multiple Domains Each instance can have its own domain. They all share the same Nginx proxy, PostgreSQL, and Redis containers, but each instance has its own isolated database. ``` panel.example.com -> Octopus Panel (frontend + backend) n8n-sales.example.com -> N8N Instance "sales" n8n-hr.example.com -> N8N Instance "hr" n8n-ops.example.com -> N8N Instance "ops" n8n-ai.example.com -> N8N Instance "ai" (with pgvector for RAG) ``` --- ## Panel Features ### Dashboard System overview: service status (PostgreSQL, Redis, Nginx), active instances, resource usage at a glance. ### Instances Create, edit, delete, start, stop, and restart N8N instances. Each instance runs its own dedicated worker for background workflow execution. Configure CPU and memory limits per instance. Start/stop instances on demand to optimize resource usage. ### Databases Manage PostgreSQL databases: create, delete, list. User management with independent permissions. PostgreSQL with pgvector support for vector storage and similarity search — ideal for AI/RAG workflows. ### SQL Editor Execute SQL queries directly from the browser against any database in the system. Real-time results with pagination. Destructive query confirmation (DROP/DELETE/TRUNCATE) prevents accidental data loss. ### Templates Save instance configurations as reusable templates. Import SQL templates to bootstrap new databases. Create fully configured instances in seconds from saved templates. ### Backups Create manual backups of any instance. Schedule automatic backups with cron expressions. One-click restore to any previous backup. Automatic cleanup of old backups based on retention policy. ### Nginx Edit Nginx configurations for each instance and the system. Validate configuration before applying. Restart the proxy from the UI. ### SSL Generate self-signed or Let's Encrypt certificates per instance. Check certificate status and expiration. Automatic renewal via cron — no manual intervention needed. --- ## Useful Commands ### Development ```bash pnpm dev # Backend + Frontend concurrently pnpm dev:backend # Backend only (with --watch) pnpm dev:frontend # Frontend only (Vite on :5173) pnpm build # Build frontend for production pnpm install:all # Install all dependencies ``` ### Production (PM2) ```bash pm2 status # Check service status pm2 logs octopus-backend # Backend logs in real time pm2 logs octopus-frontend # Frontend logs pm2 restart all # Restart everything pm2 restart octopus-backend # Restart backend only ``` ### Docker ```bash docker ps # List running containers docker logs n8nmanager-proxy # Nginx logs docker logs n8nmanager-database # PostgreSQL logs docker exec -it n8nmanager-database psql -U octopus # PostgreSQL shell docker network inspect n8nmanager-network # Inspect Docker network ``` --- ## Docker Containers | Container | Image | Ports | Purpose | |-----------|-------|-------|---------| | `n8nmanager-database` | `postgres:16-alpine` | 5432 (internal) | Shared database | | `n8nmanager-redis` | `redis:7-alpine` | 6379 (internal) | Shared job queue | | `n8nmanager-proxy` | `nginx:latest` | 80, 443 (host) | Reverse proxy with SSL | | `{name}_instance` | `n8nio/n8n` | (internal) | N8N instance | | `{name}_worker` | `n8nio/n8n` | (internal) | Instance worker | All connected to the `n8nmanager-network` bridge network. --- ## Security - API Key authentication on all endpoints (header `x-api-key` or httpOnly cookie) - Rate limiting on login endpoints (20 attempts / 15 min) - Input validation across all controllers (prevents SQL injection, command injection, path traversal) - UFW firewall configured by the installer (SSH, 80, 443 only) - SSL certificates with automatic renewal - DB and Redis passwords never exposed through the API --- ## Project Structure ``` n8n-octopus/ ├── app/ │ ├── backend/ # Express.js API (port 3000) │ │ ├── src/ │ │ │ ├── controllers/ # API handlers │ │ │ ├── services/ # Business logic (Docker, DB, Nginx, SSL, Backups) │ │ │ ├── models/ # Site, AuthKey, Settings │ │ │ ├── middleware/ # Authentication │ │ │ ├── routes/ # Route definitions │ │ │ └── utils/ # Input validation │ │ └── resources/ # Nginx templates (Handlebars) │ │ │ └── frontend/ # React + Vite (port 5173 dev / 8080 prod) │ └── src/ │ ├── pages/ # Dashboard, Instances, Databases, SQL Editor, etc. │ ├── components/ # Shared UI (ShadCN) │ ├── contexts/ # Auth, Theme │ └── lib/ # API client (Axios) │ ├── install.sh # Automatic installer for Ubuntu ├── docs/ # Additional documentation └── package.json # Monorepo scripts (pnpm workspaces) ``` --- ## API All endpoints require the `x-api-key` header (except login/verify). | Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/api/health` | Health check | | `POST` | `/api/auth/login` | Login with API Key | | `GET` | `/api/sites` | List instances | | `POST` | `/api/sites` | Create instance | | `POST` | `/api/sites/:id/start` | Start instance | | `POST` | `/api/sites/:id/stop` | Stop instance | | `DELETE` | `/api/sites/:id` | Delete instance | | `POST` | `/api/system/install` | Install system (network, DB, Redis, Nginx) | | `GET` | `/api/system/status` | System status | | `GET` | `/api/databases` | List databases | | `POST` | `/api/databases/query` | Execute SQL query | | `POST` | `/api/sites/:id/ssl/letsencrypt` | Generate Let's Encrypt certificate | | `GET` | `/api/backups/:instance` | List backups | | `POST` | `/api/backups/:instance` | Create backup | See `app/backend/src/routes/api.js` for the full list. --- ## License MIT License. See [LICENSE](LICENSE). --- ## Author Built by [@Xfirepc](https://github.com/Xfirepc) — [xfirepc.com](https://xfirepc.com) --- If you find this project useful, give it a star on GitHub.