Developing n8n Workflows
Relevant source files
The following files were used as context for generating this wiki page:
n8n serves as the central workflow engine and AI agent orchestrator within the Nyansa ecosystem. It automates tasks by connecting local LLMs, vector stores, and external data sources like Obsidian vaults. Developers use n8n to build private, local-first AI solutions that process notes and data without leaving controlled infrastructure.
Workflows in Nyansa are pre-configured to utilize a local stack consisting of Ollama for inference, Qdrant for vector storage, and a custom memory-api for Retrieval-Augmented Generation (RAG).
Sources: README.md:12-25, CONTRIBUTING.md:44-55
Workflow Architecture and Connectivity
The n8n service (nyansa-n8n) operates within an internal Docker network named nyansa. It interacts with other services using specific hostnames and ports defined in the environment.
Internal Service Integration
Workflows interact with the following internal components:
- Ollama Chat Model: Provides LLM capabilities using the
qwen2.5:3bmodel athttp://nyansa-ollama:11434. - Vector Store (Qdrant): Stores and retrieves document embeddings at
http://nyansa-qdrant:6333. - Memory API: Provides semantic search over the Obsidian vault at
http://nyansa-memory-api:8080.
The following diagram illustrates the flow of a typical AI-driven workflow within the Nyansa architecture:
Environment Configuration and Security
The Nyansa docker-compose.yml file defines strict security boundaries for n8n. Workflows cannot access the host's environment variables directly, preventing secret leakage.
Security Controls
| Feature | Implementation | Purpose |
|---|---|---|
| Environment Access | N8N_BLOCK_ENV_ACCESS_IN_NODE=true | Prevents workflows from reading container environment variables. |
| Credential Injection | CREDENTIALS_OVERWRITE_DATA | Safely injects the Qdrant API key into n8n credentials at runtime. |
| Network Isolation | Internal nyansa network | Services like Qdrant and Ollama publish no public ports. |
| File System Access | Bind Mount | The Obsidian vault is mounted read/write at /data/obsidian-vault. |
Sources: docker-compose.yml:45-66, README.md:95-120
Credential Management
n8n credentials for internal services are imported automatically during the first boot via the nyansa-n8n-import container. The Qdrant API key is never stored in the workflow JSON; instead, n8n receives it through the CREDENTIALS_OVERWRITE_DATA environment variable.
Sources: docker-compose.yml:58-60, README.md:105-110
Utilizing the Memory API (RAG)
Developers can extend n8n workflows by calling the memory-api service to perform Retrieval-Augmented Generation. The service offers two primary endpoints:
/ingest: Triggers a scan of the Obsidian vault to update the vector index./search: Performs a semantic search based on a query string.
Search Implementation Example
A workflow node can request information from the vault by sending a POST request to the internal memory service.
{
"query": "What did I write about Docker?",
"limit": 3,
"tags": ["project"],
"minScore": 0.5
}
The service returns relevant chunks including the path, title, and text of the source note, allowing the AI agent to cite its sources.
Sources: services/memory-api/README.md:39-65, README.md:20-25
Demo Workflow Structure
The project includes a Demo workflow (srOnR8PAY3u4RSwb.json) that provides a baseline for building AI chat interfaces.
Key Nodes
- Chat Trigger: Acts as the entry point for chat interactions, typically connected to the Open WebUI.
- Basic LLM Chain: Manages the prompt and communication with the language model.
- Ollama Chat Model: Configured to use
qwen2.5:3bwith credentials for the local Ollama service.
Deployment and Persistence
Workflows and their states are persisted across container restarts using a PostgreSQL database.
- State Persistence:
nyansa-postgresstores workflow definitions and execution history. - Workflow Import: On first boot, n8n imports files from
n8n/demo-data/workflows/. If workflows already exist in the database, the import is skipped. - Backups: The
scripts/backup.shscript performs a logical dump of the PostgreSQL database (postgres.dump) to ensure workflow data can be restored.
Sources: docker-compose.yml:109-122, README.md:15-18, scripts/backup.sh:58-65
Nyansa's n8n implementation prioritizes a "fastest path from zero to working AI workflows" by providing a pre-configured foundation that leverages local hardware and respects data privacy. Workflows act as the logic layer connecting the Obsidian vault to local LLM inference engines.