Self-Contained Intelligence Suite for Server Deployments

A robust, self-hosted AI environment engineered for deployment on standard VPS infrastructure. It features a curated collection of leading open-source tools including n8n, Ollama, Qdrant, Prometheus, Grafana, Whisper, Caddy, Supabase, Flowise, Open WebUI, and SearXNG.

Attribution: This architecture builds upon and enhances concepts derived from coleam00/local-ai-packaged and Digitl-Alchemyst/Automation-Stack, incorporating custom optimizations.

Core Components & Capabilities

• ✅ n8n (website): Low-code workflow engine supporting over 400 external services.
• ✅ Ollama (website): Framework for executing Large Language Models (LLMs) locally.
• ✅ Qdrant (website): Low-latency, high-throughput vector database for RAG and similarity search.
• ✅ Prometheus (website): Time-series monitoring and alerting mechanism.
• ✅ Grafana (website): Advanced dashboarding for metric visualization.
• ✅ Whisper (GitHub): Precision speech-to-text conversion module.
• ✅ Caddy (website): Automated handling of secure HTTP/TLS certificates.
• ✅ Supabase (website): Backend-as-a-Service providing database and authentication.
• ✅ Flowise (website): Visual interface for designing AI agents and chains.
• ✅ Open WebUI (website): User-friendly interface mirroring the ChatGPT experience.
• ✅ SearXNG (docs): Privacy-preserving meta-search engine integration.

System Requirements

• Operating System: Ubuntu VPS (v22.04 LTS validated).
• Networking: Access to manage DNS records for a custom domain.
• Resource Baseline: Minimum 16 Gigabytes of system RAM recommended.
• Storage: At least 100GB of disk space.
• Containerization: Docker (v20.10.0 or newer highly suggested).
• Orchestration: Docker Compose (either the plugin docker compose or the standalone binary docker-compose).

Note on Orchestration: The setup routine dynamically identifies and utilizes the appropriate docker compose command available on the host system.

Deployment Sequence

1. Establish an SSH connection to your VPS: bash ssh root@your-vps-ip

2. Install necessary system dependencies: bash sudo apt update && sudo apt install -y nano git docker.io python3 python3-pip docker-compose

3. Configure the host firewall rules (UFW): bash sudo ufw enable

Service Ports

sudo ufw allow 5678 # n8n (Adjusted to prevent Supabase port collision) sudo ufw allow 3001 # Flowise UI sudo ufw allow 8080 # Open WebUI Chat Interface sudo ufw allow 3000 # Grafana Dashboards sudo ufw allow 80 # Standard HTTP Traffic sudo ufw allow 443 # Standard HTTPS Traffic (TLS) sudo ufw allow 8000 # Supabase API Gateway (Kong) sudo ufw allow 11434 # Ollama Service Endpoint sudo ufw allow 6333 # Qdrant Vector Store sudo ufw allow 9090 # Prometheus Metrics Server sudo ufw allow 54321 # Supabase Studio/Admin Access sudo ufw reload

1. Retrieve the repository source code: bash git clone https://github.com/ThijsdeZeeuw/avg-kwintes.git cd avg-kwintes

2. Execute the preliminary configuration script to ready the environment: bash

Grant execution permission

chmod +x fix_config.sh

Run the preparatory setup script

sudo ./fix_config.sh

This script handles dependency verification, firewall rule confirmation, port conflict resolution, generation of maintenance utilities, and creation of the initial .env configuration file.

1. Initiate the interactive setup wizard for final adjustments: bash python3 start_services.py --interactive

2. Launch the entire AI service cluster (CPU-optimized profile): bash python3 start_services.py --profile cpu

This staged approach guarantees all infrastructure and network prerequisites are established before runtime, minimizing startup failures related to port contention or missing resources.

Operational Utilities

Post-installation, several helper scripts are generated for routine management:

System Update Procedure

To synchronize the Local AI Stack with the newest container images and configuration standards: bash sudo ./update_stack.sh

This command pulls the latest Docker images, re-applies configuration fixes, and restarts all dependent services.

Data Preservation Routine

To generate a complete, timestamped archive of all persistent data (volumes, configurations, secrets): bash sudo ./backup_stack.sh

Preloaded AI Models (Ollama)

The initialization process automatically downloads and stages the following models:

Generative & Instruction Models (LLMs)

Model Identifier	Origin	Purpose Summary
gemma3:12b	Google	12 Billion parameter model for general text tasks.
granite3-guardian:8b	IBM	8B parameter model emphasizing safety and ethical guardrails.
granite3.1-dense:latest	IBM	Current stable dense transformer for broad NLP tasks.
granite3.1-moe:3b	IBM	Efficient 3B parameter Mixture-of-Experts version.
granite3.2:latest	IBM	Latest iteration of IBM's advanced language model series.
llama3.2-vision	Meta	Multimodal model supporting both image and text inputs.
minicpm-v:8b	OpenBMB	Optimized 8B model suitable for constrained environments.
mistral-nemo:12b	Mistral AI	12B model leveraging Mistral architecture enhancements.
qwen2.5:7b-instruct-q4_K_M	Alibaba	Quantized (Q4) 7B instruction-tuned model for efficiency.
reader-lm:latest	OpenBMB	Specialized model designed for deep document comprehension and QA.

Semantic Vector Models (Embeddings)

Model Identifier	Origin	Purpose Summary
granite-embedding:278m	IBM	Lightweight embedding model for efficient vector representation.
jeffh/intfloat-multilingual-e5-large-instruct:f16	Hugging Face	High-quality multilingual embedding model tuned for instructions.
nomic-embed-text:latest	Nomic AI	General-purpose model for semantic search accuracy.

Inference capabilities adapt automatically; the system defaults to CPU processing unless compatible NVIDIA or AMD hardware is detected and configured.

Service Endpoint Access Map

Once operational, the services are reachable via:

• Workflow Automation (n8n): https://n8n.kwintes.cloud
• Conversational AI Interface (WebUI): https://openwebui.kwintes.cloud
• AI Agent Builder (Flowise): https://flowise.kwintes.cloud
• Backend Database (Supabase): https://supabase.kwintes.cloud
• Database Management UI (Studio): http://localhost:54321 or https://studio.supabase.kwintes.cloud
• Performance Metrics (Grafana): https://grafana.kwintes.cloud
• Metric Collection (Prometheus): https://prometheus.kwintes.cloud
• Speech Transcription API (Whisper): https://whisper.kwintes.cloud
• Vector Search API (Qdrant): https://qdrant.kwintes.cloud

Observability Guide

The monitoring stack is ready for immediate use:

1. Access Grafana at https://grafana.kwintes.cloud
2. Default Login: User admin / Password found within secrets.txt.

3. Ensure Prometheus is registered as a data source (Target URL: http://prometheus:9090).

4. Access Prometheus at https://prometheus.kwintes.cloud

5. Review collected metrics and configure alerting rules.

Security Protocols Summary

Security is enforced through a layered approach:

1. Data Localization: All model inference and data processing remain strictly confined to the dedicated VPS environment.
2. Traffic Encryption: Caddy ensures all external service endpoints utilize HTTPS/TLS by default.
3. Network Hardening: The firewall is configured to expose only essential service ports.
4. Credential Management: Sensitive configuration data is isolated in secrets.txt.
5. Access Control: Supabase provides mechanisms for user authentication and authorization checks.

Maintenance Operations

To keep the system current:

Stack Update: bash cd avg-kwintes python3 start_services.py --profile cpu

(Note: This relies on the update script being run first, or the start_services.py pulling the latest images if configured to do so).

Service Cycle Restart (if manual intervention is needed): bash docker compose -f docker-compose.yml down python3 start_services.py --profile cpu

Troubleshooting Common Issues

1. Docker Compose Command Error (e.g., unknown shorthand flag: 'p') This signals an incompatibility between the syntax used (docker compose -p) and the installed version (often older standalone binaries).

Resolution: The installer script attempts to auto-detect. If manual CLI use fails, verify you are using the plugin (docker compose) or install the standalone v2 binary: bash sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose

1. Checking Running Processes: bash docker compose -p avg-kwintes ps

OR

docker-compose -p avg-kwintes ps

1. Viewing Specific Container Output: bash docker compose -p avg-kwintes logs -f [service_name]

== Cloud Computing Foundation (Contextual Reference) ==

Cloud computing, defined by ISO as granting 'network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning,' is commonly termed 'the cloud.'

Essential Characteristics (NIST 2011)

1. Self-Service On-Demand: Consumers provision capacity (servers, storage) automatically without provider intervention.
2. Broad Network Availability: Services are accessible via standard protocols across diverse client devices (mobile, desktop).
3. Resource Pooling: Provider resources are shared across multiple tenants dynamically, allocating capacity based on demand.
4. Rapid Elasticity: Capabilities can scale up or down quickly, often automatically, appearing limitless to the user.
5. Measured Utility: Resource consumption (storage, compute time, bandwidth) is automatically tracked, reported, and optimized, ensuring transparency.

Historical Context

The genesis of cloud concepts dates back to the 1960s with the popularization of time-sharing systems, which moved computing from single-user mainframe access to shared, remote job entry (RJE).

The graphical 'cloud' metaphor for networked, virtualized environments was first employed in 1994 by General Magic for their Telescript platform, credited to communications specialist David Hoffman. The term 'cloud computing' gained widespread industry visibility in 1996 through internal planning documents at Compaq Computer Corporation concerning the future of the internet.