From 8e2d05c1e857b3227f44da44a4b742c0c4cf00be Mon Sep 17 00:00:00 2001 From: Yury Kossakovsky Date: Mon, 5 May 2025 14:01:46 -0600 Subject: [PATCH] Update README.md to reflect project rebranding and enhancements - Renamed the project from "Self-hosted AI Package" to "n8n Ecosystem Installer" for clarity. - Expanded the description to highlight the comprehensive development environment setup, including new tools like Flowise, Langfuse, and Crawl4ai. - Added details about the automatic import of community workflows and the option to include over 300 workflows during setup. - Updated installation instructions to emphasize the use of the new installation script for a streamlined setup process. - Included monitoring setup instructions for Prometheus and Grafana, enhancing the documentation for user guidance. --- README.md | 282 ++++++++++++++++++++++++------------------------------ 1 file changed, 125 insertions(+), 157 deletions(-) diff --git a/README.md b/README.md index 7dedebb..dd78099 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,22 @@ -# Self-hosted AI Package +# n8n Ecosystem Installer -**Self-hosted AI Package** is an open, docker compose template that -quickly bootstraps a fully featured Local AI and Low Code development -environment including Ollama for your local LLMs, Open WebUI for an interface to chat with your N8N agents, and Supabase for your database, vector store, and authentication. +**n8n Ecosystem Installer** is an open, docker compose template designed to significantly simplify the setup of a comprehensive development environment centered around n8n and Flowise. It bundles essential supporting tools like Open WebUI (as an interface for n8n agents), Supabase (database, vector store, auth), Qdrant (high-performance vector store), Langfuse (LLM observability), SearXNG (private metasearch), Grafana/Prometheus (monitoring), Crawl4ai (web crawling), and Caddy (managed HTTPS). This is Cole's version with a couple of improvements and the addition of Supabase, Open WebUI, Flowise, Langfuse, SearXNG, and Caddy! -Also, the local RAG AI Agent workflows from the video will be automatically in your -n8n instance if you use this setup instead of the base one provided by n8n! +Also, the RAG AI Agent workflows from the video will be automatically in your +n8n instance if you use this setup instead of the base one provided by n8n! Note: these workflows might require external LLM API keys or a separate Ollama instance if you wish to use local models. +Also, you have the option during setup to automatically import over 300 community workflows into your n8n instance! ## Important Links +- Forked from [coleam00/local-ai-packaged](https://github.com/coleam00/local-ai-packaged) + +- [Original Local AI Starter Kit](https://github.com/n8n-io/self-hosted-ai-starter-kit) by the n8n team + - [Local AI community](https://thinktank.ottomator.ai/c/local-ai/18) forum over in the oTTomator Think Tank - [GitHub Kanban board](https://github.com/users/coleam00/projects/2/views/1) for feature implementation and bug squashing. -- [Original Local AI Starter Kit](https://github.com/n8n-io/self-hosted-ai-starter-kit) by the n8n team - - Download my N8N + OpenWebUI integration [directly on the Open WebUI site.](https://openwebui.com/f/coleam/n8n_pipe/) (more instructions below) ![n8n.io - Screenshot](https://raw.githubusercontent.com/n8n-io/self-hosted-ai-starter-kit/main/assets/n8n-demo.gif) @@ -24,7 +25,7 @@ Curated by and , it com platform with a curated list of compatible AI products and components to quickly get started with building self-hosted AI workflows. -### What’s included +### What's included ✅ [**Self-hosted n8n**](https://n8n.io/) - Low-code platform with over 400 integrations and advanced AI components @@ -32,9 +33,6 @@ integrations and advanced AI components ✅ [**Supabase**](https://supabase.com/) - Open source database as a service - most widely used database for AI agents -✅ [**Ollama**](https://ollama.com/) - Cross-platform LLM platform to install -and run the latest local LLMs - ✅ [**Open WebUI**](https://openwebui.com/) - ChatGPT-like interface to privately interact with your local models and N8N agents @@ -45,13 +43,19 @@ builder that pairs very well with n8n store with an comprehensive API. Even though you can use Supabase for RAG, this was kept unlike Postgres since it's faster than Supabase so sometimes is the better option. -✅ [**SearXNG**](https://searxng.org/) - Open source, free internet metasearch engine which aggregates +✅ [**SearXNG**](https://searxng.org/) - Open source, free internet metasearch engine which aggregates results from up to 229 search services. Users are neither tracked nor profiled, hence the fit with the local AI package. ✅ [**Caddy**](https://caddyserver.com/) - Managed HTTPS/TLS for custom domains ✅ [**Langfuse**](https://langfuse.com/) - Open source LLM engineering platform for agent observability +✅ [**Crawl4ai**](https://github.com/Alfresco/crawl4ai) - Flexible web crawler designed for AI data extraction workflows. + +✅ [**Prometheus**](https://prometheus.io/) - Open source monitoring and alerting toolkit. + +✅ [**Grafana**](https://grafana.com/) - Open source platform for monitoring and observability, often used with Prometheus. + ## Prerequisites Before you begin, make sure you have the following software installed: @@ -63,121 +67,75 @@ Before you begin, make sure you have the following software installed: ## Installation Clone the repository and navigate to the project directory: + ```bash git clone https://github.com/coleam00/local-ai-packaged.git cd local-ai-packaged ``` +### Quick Start with Scripts + +The recommended way to install is using the provided scripts. Run the main installation script: + +```bash +sudo bash ./scripts/install.sh +``` + +This script automates the entire setup process, including: + +- System preparation (updates, firewall configuration with UFW, Fail2Ban setup). +- Docker and Docker Compose installation. +- Generation of the `.env` configuration file with necessary secrets. +- Launching all the services. + +During the installation, the script will ask you for: + +1. Your primary domain name (e.g., `yourdomain.com`) for accessing services. +2. Your email address (used for service logins like Flowise, Supabase dashboard, Grafana, Prometheus, SearXNG, and for Let's Encrypt SSL certificates). +3. An optional OpenAI API key (used by Supabase AI features and Crawl4ai). +4. Whether you want to import ~300 ready-made n8n community workflows (this can take ~30 minutes). + +Upon completion, the script will display a summary report containing the access URLs and credentials for the deployed services. + Before running the services, you need to set up your environment variables for Supabase following their [self-hosting guide](https://supabase.com/docs/guides/self-hosting/docker#securing-your-services). -1. Make a copy of `.env.example` and rename it to `.env` in the root directory of the project -2. Set the following required environment variables: - ```bash - ############ - # N8N Configuration - ############ - N8N_ENCRYPTION_KEY= - N8N_USER_MANAGEMENT_JWT_SECRET= - - ############ - # Supabase Secrets - ############ - POSTGRES_PASSWORD= - JWT_SECRET= - ANON_KEY= - SERVICE_ROLE_KEY= - DASHBOARD_USERNAME= - DASHBOARD_PASSWORD= - POOLER_TENANT_ID= - - ############ - # Langfuse credentials - ############ - - CLICKHOUSE_PASSWORD= - MINIO_ROOT_PASSWORD= - LANGFUSE_SALT= - NEXTAUTH_SECRET= - ENCRYPTION_KEY= - ``` - -> [!IMPORTANT] -> Make sure to generate secure random values for all secrets. Never use the example values in production. - -3. Set the following environment variables if deploying to production, otherwise leave commented: - ```bash - ############ - # Caddy Config - ############ - - N8N_HOSTNAME=n8n.yourdomain.com - WEBUI_HOSTNAME=:openwebui.yourdomain.com - FLOWISE_HOSTNAME=:flowise.yourdomain.com - SUPABASE_HOSTNAME=:supabase.yourdomain.com - OLLAMA_HOSTNAME=:ollama.yourdomain.com - SEARXNG_HOSTNAME=searxng.yourdomain.com - LETSENCRYPT_EMAIL=your-email-address - ``` - ---- - -The project includes a `start_services.py` script that handles starting both the Supabase and local AI services. The script accepts a `--profile` flag to specify which GPU configuration to use. - -### For Nvidia GPU users - -```bash -python start_services.py --profile gpu-nvidia -``` - > [!NOTE] -> If you have not used your Nvidia GPU with Docker before, please follow the -> [Ollama Docker instructions](https://github.com/ollama/ollama/blob/main/docs/docker.md). +> The `install.sh` script handles the creation and population of the `.env` file based on `.env.example` and the information you provide. You typically do not need to manually create or edit this file unless making advanced customizations _after_ the initial setup. -### For AMD GPU users on Linux +The script will generate secure values for necessary secrets like: -```bash -python start_services.py --profile gpu-amd -``` +- `N8N_ENCRYPTION_KEY` +- `N8N_USER_MANAGEMENT_JWT_SECRET` +- `POSTGRES_PASSWORD` +- `JWT_SECRET` +- `ANON_KEY` (derived from JWT_SECRET) +- `SERVICE_ROLE_KEY` (derived from JWT_SECRET) +- `DASHBOARD_PASSWORD` +- `CLICKHOUSE_PASSWORD` +- `MINIO_ROOT_PASSWORD` +- `LANGFUSE_SALT` +- `NEXTAUTH_SECRET` +- `ENCRYPTION_KEY` (Langfuse) +- `GRAFANA_ADMIN_PASSWORD` +- And others... -### For Mac / Apple Silicon users +> The installation script handles the generation of these secrets automatically. -If you're using a Mac with an M1 or newer processor, you can't expose your GPU to the Docker instance, unfortunately. There are two options in this case: +The script will also configure hostnames in the `.env` file based on the domain you provide, for example: -1. Run the starter kit fully on CPU: - ```bash - python start_services.py --profile cpu - ``` +- `N8N_HOSTNAME=n8n.yourdomain.com` +- `WEBUI_HOSTNAME=openwebui.yourdomain.com` +- `FLOWISE_HOSTNAME=flowise.yourdomain.com` +- `SUPABASE_HOSTNAME=supabase.yourdomain.com` +- `SEARXNG_HOSTNAME=searxng.yourdomain.com` +- `LANGFUSE_HOSTNAME=langfuse.yourdomain.com` +- `GRAFANA_HOSTNAME=grafana.yourdomain.com` +- `PROMETHEUS_HOSTNAME=prometheus.yourdomain.com` +- `LETSENCRYPT_EMAIL=your-email-address` (filled with the email you provide) -2. Run Ollama on your Mac for faster inference, and connect to that from the n8n instance: - ```bash - python start_services.py --profile none - ``` +Service Startup - If you want to run Ollama on your mac, check the [Ollama homepage](https://ollama.com/) for installation instructions. - -#### For Mac users running OLLAMA locally - -If you're running OLLAMA locally on your Mac (not in Docker), you need to modify the OLLAMA_HOST environment variable in the n8n service configuration. Update the x-n8n section in your Docker Compose file as follows: - -```yaml -x-n8n: &service-n8n - # ... other configurations ... - environment: - # ... other environment variables ... - - OLLAMA_HOST=host.docker.internal:11434 -``` - -Additionally, after you see "Editor is now accessible via: http://localhost:5678/": - -1. Head to http://localhost:5678/home/credentials -2. Click on "Local Ollama service" -3. Change the base URL to "http://host.docker.internal:11434/" - -### For everyone else - -```bash -python start_services.py --profile cpu -``` +The `install.sh` script automatically starts all services using Docker Compose after the configuration is complete. You generally do not need to start services manually after the initial installation. If you need to restart services after stopping them manually, the `scripts/04_run_services.sh` script can be used, or you can manage them via standard `docker compose` commands (though using the provided scripts is recommended). ## Deploying to the Cloud @@ -190,94 +148,90 @@ python start_services.py --profile cpu Before running the above commands to pull the repo and install everything: 1. Run the commands as root to open up the necessary ports: + - ufw enable - ufw allow 8000 && ufw allow 3000 && ufw allow 5678 && ufw allow 3002 && ufw allow 80 && ufw allow 443 - ufw allow 3001 (if you want to expose Flowise, you will have to set up the [environment variables](https://docs.flowiseai.com/configuration/environment-variables) to enable authentication) - ufw allow 8080 (if you want to expose SearXNG) - - ufw allow 11434 (if you want to expose Ollama) - ufw reload 2. Set up A records for your DNS provider to point your subdomains you'll set up in the .env file for Caddy -to the IP address of your cloud instance. + to the IP address of your cloud instance. For example, A record to point n8n to [cloud instance IP] for n8n.yourdomain.com ## ⚡️ Quick start and usage The main component of the self-hosted AI starter kit is a docker compose file -pre-configured with network and disk so there isn’t much else you need to +pre-configured with network and disk so there isn't much else you need to install. After completing the installation steps above, follow the steps below to get started. -1. Open in your browser to set up n8n. You’ll only +1. Open in your browser to set up n8n. You'll only have to do this once. You are NOT creating an account with n8n in the setup here, it is only a local account for your instance! 2. Open the included workflow: 3. Create credentials for every service: - - Ollama URL: http://ollama:11434 Postgres (through Supabase): use DB, username, and password from .env. IMPORTANT: Host is 'db' - Since that is the name of the service running Supabase + (name of the Supabase Postgres service within the Docker network). Qdrant URL: http://qdrant:6333 (API key can be whatever since this is running locally) Google Drive: Follow [this guide from n8n](https://docs.n8n.io/integrations/builtin/credentials/google/). Don't use localhost for the redirect URI, just use another domain you have, it will still work! Alternatively, you can set up [local file triggers](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.localfiletrigger/). + 4. Select **Test workflow** to start running the workflow. -5. If this is the first time you’re running the workflow, you may need to wait - until Ollama finishes downloading Llama3.1. You can inspect the docker - console logs to check on the progress. -6. Make sure to toggle the workflow as active and copy the "Production" webhook URL! -7. Open in your browser to set up Open WebUI. -You’ll only have to do this once. You are NOT creating an account with Open WebUI in the -setup here, it is only a local account for your instance! -8. Go to Workspace -> Functions -> Add Function -> Give name + description then paste in -the code from `n8n_pipe.py` +5. Make sure to toggle the workflow as active and copy the "Production" webhook URL! +6. Open in your browser to set up Open WebUI. + You'll only have to do this once. You are NOT creating an account with Open WebUI in the + setup here, it is only a local account for your instance! +7. Go to Workspace -> Functions -> Add Function -> Give name + description then paste in + the code from `n8n_pipe.py` The function is also [published here on Open WebUI's site](https://openwebui.com/f/coleam/n8n_pipe/). -9. Click on the gear icon and set the n8n_url to the production URL for the webhook -you copied in a previous step. -10. Toggle the function on and now it will be available in your model dropdown in the top left! +8. Click on the gear icon and set the n8n_url to the production URL for the webhook + you copied in a previous step. +9. Toggle the function on and now it will be available in your model dropdown in the top left! To open n8n at any time, visit in your browser. To open Open WebUI at any time, visit . -With your n8n instance, you’ll have access to over 400 integrations and a +With your n8n instance, you'll have access to over 400 integrations and a suite of basic and advanced AI nodes such as [AI Agent](https://docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/), [Text classifier](https://docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.text-classifier/), and [Information Extractor](https://docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.information-extractor/) nodes. To keep everything local, just remember to use the Ollama node for your -language model and Qdrant as your vector store. +language model (if configured) and Qdrant or Supabase as your vector store. +nodes. Remember to use Qdrant or Supabase as your vector store. If you wish to use local language models, you can configure the Ollama node in n8n, assuming you have an Ollama instance running separately. > [!NOTE] > This starter kit is designed to help you get started with self-hosted AI -> workflows. While it’s not fully optimized for production environments, it +> workflows. While it's not fully optimized for production environments, it +> This installer is designed to help you get started quickly with n8n and related tools. While it's not fully optimized for production environments, it > combines robust components that work well together for proof-of-concept > projects. You can customize it to meet your specific needs ## Upgrading To update all containers to their latest versions (n8n, Open WebUI, etc.), run these commands: +and pull the latest changes from the repository, use the update script: ```bash -# Stop all services -docker compose -p localai --profile -f docker-compose.yml -f supabase/docker/docker-compose.yml down - -# Pull latest versions of all containers -docker compose -p localai --profile -f docker-compose.yml -f supabase/docker/docker-compose.yml pull - -# Start services again with your desired profile -python start_services.py --profile +sudo bash ./scripts/update.sh ``` -Replace `` with one of: `cpu`, `gpu-nvidia`, `gpu-amd`, or `none`. +This script will: -Note: The `start_services.py` script itself does not update containers - it only restarts them or pulls them if you are downloading these containers for the first time. To get the latest versions, you must explicitly run the commands above. +1. Pull the latest changes from the Git repository. +2. Stop the currently running services using `docker compose down`. +3. Pull the latest Docker images for all services using `docker compose pull`. +4. Ask if you want to re-run the n8n workflow import (useful if new workflows were added). +5. Restart the services using the `scripts/04_run_services.sh` script. ## Troubleshooting @@ -293,15 +247,6 @@ Here are solutions to common issues you might encounter: - **Supabase Service Unavailable** - Make sure you don't have an "@" character in your Postgres password! If the connection to the kong container is working (the container logs say it is receiving requests from n8n) but n8n says it cannot connect, this is generally the problem from what the community has shared. Other characters might not be allowed too, the @ symbol is just the one I know for sure! -### GPU Support Issues - -- **Windows GPU Support**: If you're having trouble running Ollama with GPU support on Windows with Docker Desktop: - 1. Open Docker Desktop settings - 2. Enable WSL 2 backend - 3. See the [Docker GPU documentation](https://docs.docker.com/desktop/features/gpu/) for more details - -- **Linux GPU Support**: If you're having trouble running Ollama with GPU support on Linux, follow the [Ollama Docker instructions](https://github.com/ollama/ollama/blob/main/docs/docker.md). - ## 👓 Recommended reading n8n is full of useful content for getting started quickly with its AI concepts @@ -337,17 +282,20 @@ your local n8n instance. - [Tax Code Assistant](https://n8n.io/workflows/2341-build-a-tax-code-assistant-with-qdrant-mistralai-and-openai/) - [Breakdown Documents into Study Notes with MistralAI and Qdrant](https://n8n.io/workflows/2339-breakdown-documents-into-study-notes-using-templating-mistralai-and-qdrant/) -- [Financial Documents Assistant using Qdrant and](https://n8n.io/workflows/2335-build-a-financial-documents-assistant-using-qdrant-and-mistralai/) [ Mistral.ai](http://mistral.ai/) +- [Financial Documents Assistant using Qdrant and](https://n8n.io/workflows/2335-build-a-financial-documents-assistant-using-qdrant-and-mistralai/) [Mistral.ai](http://mistral.ai/) - [Recipe Recommendations with Qdrant and Mistral](https://n8n.io/workflows/2333-recipe-recommendations-with-qdrant-and-mistral/) +### Example AI templates (May require external APIs or separate local model setup) + ## Tips & tricks ### Accessing local files The self-hosted AI starter kit will create a shared folder (by default, +The installer will create a shared folder (by default, located in the same directory) which is mounted to the n8n container and allows n8n to access files on disk. This folder within the n8n container is -located at `/data/shared` -- this is the path you’ll need to use in nodes that +located at `/data/shared` -- this is the path you'll need to use in nodes that interact with the local filesystem. **Nodes that interact with the local filesystem** @@ -356,7 +304,27 @@ interact with the local filesystem. - [Local File Trigger](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.localfiletrigger/) - [Execute Command](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.executecommand/) -## 📜 License +## 📜 License This project (originally created by the n8n team, link at the top of the README) is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details. + +## Monitoring n8n with Prometheus and Grafana + +Prometheus and Grafana are included for monitoring your n8n instance. + +- Prometheus: http://localhost:9090/ or https://prometheus.a2.fyi/ +- Grafana: http://localhost:3002/ or https://grafana.a2.fyi/ (default admin password is set in `.env`) + +**To add n8n metrics:** + +- n8n exposes metrics at `http://n8n:5678/metrics` (if not, see n8n docs for enabling Prometheus metrics). +- Prometheus is pre-configured to scrape n8n metrics. +- Grafana can be configured to use Prometheus as a data source (default URL: `http://prometheus:9090`). + +**Default credentials for Grafana:** + +- Username: admin +- Password: (set in `.env` as `GRAFANA_ADMIN_PASSWORD`) + +You can import community dashboards for n8n or create your own!