Octopus

Orchestration system for managing multiple N8N workflow automation instances on a single server.
Shared PostgreSQL, shared Redis, centralized Nginx reverse proxy with automatic SSL — all from a web panel.

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

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

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:

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

# 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)

Frontend (app/frontend/.env)

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

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)

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

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

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).

See app/backend/src/routes/api.js for the full list.

License

MIT License. See LICENSE.

Author

Built by @Xfirepc — xfirepc.com

If you find this project useful, give it a star on GitHub.