KNIRV-NEXUS: Decentralized Validation Environment



KNIRV-NEXUS is a unified implementation of the Decentralized Validation Environment (DVE) for the KNIRV Network. It provides a secure, scalable platform for validating SkillNodes and Base LLMs using a modern architecture that combines Next.js frontend with Go backend services in a single deployable binary.

๐Ÿ—๏ธ Architecture Overview



KNIRV-NEXUS implements a unified architecture with embedded frontend and backend services:

Unified Binary Architecture



- Main Wrapper (main.go): Embeds both frontend and backend into a single executable
- Frontend Embedding: Next.js build output embedded via //go:embed all:out
- Backend Embedding: Unified backend binary embedded via //go:embed bin/nexus-backend
- API Proxy: Gin-based proxy routing /api/* requests to embedded backend
- Static Serving: Embedded filesystem serving Next.js static assets

Core Backend Services



- DVE Manager: Orchestrates DVE nodes, manages task allocation, and monitors system health
- Validation Core: Executes validation tasks with TEE support and cryptographic proofs
- Agent Server: Manages WASM plugin agents and runtime execution
- Data Engine: BuntDB-based data processing, metrics aggregation, and alerting
- CDE Service: Cloud Development Environments for isolated execution
- DNS Service: Dynamic DNS management for distributed nodes
- P2P Manager: libp2p-based networking for node discovery and communication

> Note: KNIRV-NEXUS integrates with KNIRVGATEWAY for production routing. The unified architecture enables both standalone deployment and gateway integration.

Frontend Technology Stack



- Framework: Next.js 15 with App Router
- UI Components: shadcn/ui built on Radix UI primitives
- Styling: Tailwind CSS 4 with custom KNIRV theme
- Real-time: Socket.io for live updates and notifications
- State Management: React hooks and context
- Type Safety: TypeScript with strict configuration
- Authentication: Role-based access control with JWT
- Embedding: Static build output embedded in Go binary

Backend Infrastructure



- Language: Go 1.21+ with modern concurrency patterns
- Database: BuntDB (embedded key-value store with custom indexes)
- Networking: libp2p for P2P communication and node discovery
- Configuration: Viper for hierarchical configuration management
- Web Framework: Gorilla Mux for HTTP routing and middleware
- Real-time: WebSocket support for live data streaming
- Container Runtime: Podman (rootless containers) for production
- Orchestration: Kubernetes with production-ready configurations

๐Ÿงช Phase 7 Testing Infrastructure



Testing Architecture


KNIRVNEXUS implements comprehensive testing across multiple layers:

#### Backend Testing (Go)
bash

Run backend unit tests


cd backend && go test -v ./tests/...

Run specific test suites


go test -v ./tests/phase6_comprehensive_unit_test.go
go test -v ./tests/integration_test.go
go test -v ./tests/architecture_test.go


#### Frontend Testing (Next.js)
bash

Run frontend tests


npm test

Type checking


npm run type-check

Linting


npm run lint


#### Integration with Network Tests
bash

From project root - run KNIRVNEXUS network integration tests


cd integration-tests && go test -v -run TestKNIRVNEXUS

Run comprehensive KNIRVNEXUS test suite


make test-nexus

Run specific test categories


make test-nexus-unit # Unit tests only
make test-nexus-integration # Integration tests only
make test-nexus-e2e # End-to-end tests only
make test-nexus-performance # Performance tests only
make test-nexus-security # Security tests only


๐Ÿ› ๏ธ Build System



KNIRV-NEXUS uses a unified build process that creates a single deployable binary containing both frontend and backend:

Build Process Overview



1. Frontend Build: Next.js builds static output to out/ directory
2. Backend Build: Go builds unified backend binary to bin/nexus-backend
3. Embedding: Main wrapper embeds both frontend and backend using go:embed
4. Final Binary: Single executable containing complete application

Core Build Commands



bash

Quick Development Setup


npm install # Install frontend dependencies
npm run build # Build Next.js frontend
cd backend && go build -o ../bin/nexus-backend ./main.go # Build backend
go build -o knirv-nexus main.go # Build unified binary

Development Mode


npm run dev # Start Next.js dev server (port 3000)
cd backend && go run main.go --config config/development.yaml # Backend only

Production Build


npm run build # Build optimized frontend
cd backend && CGO_ENABLED=1 go build -ldflags="-s -w" -o ../bin/nexus-backend ./main.go
go build -ldflags="-s -w -X main.Version=v1.0.0" -o knirv-nexus main.go

Testing


npm test # Frontend tests
cd backend && go test ./... # Backend tests


Deployment Options



bash

Standalone Binary


./knirv-nexus # Runs on port 8090 (configurable)

With Custom Configuration


./knirv-nexus --config config/production.yaml

Environment Variables


NEXUS_PORT=8080 NEXUS_BACKEND_PORT=8081 ./knirv-nexus

Docker Deployment


docker build -t knirv/nexus:latest .
docker run -p 8090:8090 knirv/nexus:latest


๐Ÿš€ Current Implementation Status



โœ… Fully Implemented Features



#### Unified Architecture
- Single Binary Deployment: Frontend and backend embedded in one executable
- Embedded Frontend: Next.js build output served via Go's embed filesystem
- API Proxy: Gin-based routing of /api/* requests to embedded backend
- Configuration Management: Viper-based hierarchical configuration with YAML support

#### Frontend (Next.js with shadcn/ui)
- Modern UI Framework: Next.js 15 with App Router and TypeScript
- Component Library: Complete shadcn/ui component set built on Radix UI
- Dashboard Interface: Comprehensive dashboard with tabs for all major functions
- Responsive Design: Mobile-first design with Tailwind CSS and KNIRV theme
- Authentication UI: Role-based components and user profile management

#### Backend Services
- DVE Manager: Node orchestration and task allocation service
- Validation Core: Task queue and validation execution framework
- Agent Server: WASM plugin agent management and runtime execution
- Data Engine: BuntDB-based metrics, alerts, and event processing
- CDE Service: Cloud Development Environment management
- DNS Service: Dynamic DNS management for distributed nodes

#### Database & Storage
- BuntDB Integration: Embedded key-value store with custom indexes
- Data Engine: Comprehensive metrics aggregation and alerting system
- Event Processing: Real-time event ingestion and processing pipeline
- Report Generation: User and system report storage and retrieval

โš ๏ธ Partially Implemented Features



#### P2P Networking (30% Complete)
- Basic Structure: libp2p manager framework in place
- Missing: DHT integration, GossipSub messaging, active node discovery
- Status: Foundation exists but not operational

#### Validation Engine (40% Complete)
- Task Management: Queue system and basic task structures
- Missing: Actual validation logic, cryptographic proof generation
- Status: Framework ready but core functionality incomplete

#### API Endpoints (50% Complete)
- Route Structure: All service routes defined with proper handlers
- Missing: Complete CRUD operations, many endpoints return placeholder data
- Status: Infrastructure ready but implementations incomplete

โŒ Missing Critical Features



#### TEE (Trusted Execution Environment)
- Status: Only basic type definitions exist
- Missing: SGX/SEV-SNP/TDX integration, attestation, secure execution
- Impact: Core security guarantees not implemented

#### JWT Authentication System
- Status: Frontend auth components exist but no backend implementation
- Missing: JWT middleware, user management, role-based access control
- Impact: Security model incomplete

#### Real-time Updates
- Status: Frontend expects Socket.io, backend has basic WebSocket stubs
- Missing: Functional Socket.io server, SSE implementation
- Impact: Dashboard real-time features non-functional

#### Operational Modes (GUI/Headless)
- Status: Documented but not implemented
- Missing: Mode switching logic, GUI-specific configurations
- Impact: Deployment flexibility limited

> Note: See Nexus_Gap_Analysis.md for detailed analysis of implementation gaps and recommended actions.

๐Ÿš€ Quick Start



Prerequisites



- Go 1.21+: Required for backend compilation
- Node.js 18+: Required for frontend development and building
- npm: Package manager for frontend dependencies
- Git: Version control for cloning repository

Quick Development Setup



Get started in 5 minutes:

bash

1. Clone repository


git clone https://github.com/knirv/KNIRV_NETWORK.git
cd KNIRV_NETWORK/KNIRVNEXUS

2. Install frontend dependencies


npm install

3. Build frontend


npm run build

4. Build backend


cd backend
go mod tidy
go build -o ../bin/nexus-backend ./main.go
cd ..

5. Build unified binary


go build -o knirv-nexus main.go

6. Run application


./knirv-nexus

7. Access application at http://localhost:8090




For development with hot reload:

bash

Terminal 1: Frontend development server


npm run dev # Runs on http://localhost:3000

Terminal 2: Backend development server


cd backend
go run main.go --config config/development.yaml # Runs on http://localhost:8080


Deployment



1. Clone the repository:
bash
git clone https://github.com/knirv/KNIRV_NETWORK.git
cd KNIRV_NETWORK/KNIRVNEXUS


2. Build the components:
bash
chmod +x scripts/build.sh
./scripts/build.sh


3. Deploy to Kubernetes:
bash
chmod +x scripts/deploy.sh
./scripts/deploy.sh


4. Verify deployment:
bash
kubectl get pods -n knirv-nexus


Development Setup



#### Frontend Development
1. Install frontend dependencies:
bash
npm install


2. Start development server:
bash
npm run dev


3. Build frontend:
bash
npm run build


4. Start custom server with Socket.io:
bash
npm run start


#### Backend Development

##### Prerequisites
- Go 1.21+ installed
- Git for version control
- Optional: Docker for containerized builds

##### Environment Setup

1. Set up environment variables:
bash
# For development (GUI mode, no auth required)
cp .env.development .env

# OR for production (headless mode, auth required)
cp .env.production .env
# Then set JWT_SECRET environment variable:
export JWT_SECRET="your-secure-jwt-secret-here"


2. Install backend dependencies:
bash
cd backend
go mod tidy


3. Create required directories:
bash
mkdir -p data logs reports keys


##### Building the Backend

1. Quick development build:
bash
cd backend

# Build DVE Manager
go build -o bin/dve-manager ./cmd/dve-manager/

# Build Validation Core
go build -o bin/validation-core ./cmd/validation-core/

# Build API Gateway (if available)
go build -o bin/api-gateway ./cmd/api-gateway/


2. Production build (static linking):
bash
cd backend

# Build with static linking for containers
CGO_ENABLED=1 GOOS=linux go build -a -installsuffix cgo \
-ldflags '-extldflags "-static" -s -w' \
-o bin/dve-manager ./cmd/dve-manager/

CGO_ENABLED=1 GOOS=linux go build -a -installsuffix cgo \
-ldflags '-extldflags "-static" -s -w' \
-o bin/validation-core ./cmd/validation-core/


3. Using the build script:
bash
# Full build with Docker images
./scripts/build.sh

# Build binaries only (skip Docker)
./scripts/build.sh --skip-docker

# Skip tests and security checks
./scripts/build.sh --skip-tests --skip-security


##### Running the Services

1. Development mode (with GUI):
bash
cd backend

# Load development environment
export $(cat ../.env.development | xargs)

# Run DVE Manager with GUI
./bin/dve-manager --gui

# In another terminal, run Validation Core with GUI
./bin/validation-core --gui


2. Production mode (headless):
bash
cd backend

# Load production environment
export $(cat ../.env.production | xargs)
export JWT_SECRET="your-secure-jwt-secret"

# Run services
./bin/dve-manager
./bin/validation-core


3. With custom configuration:
bash
./bin/dve-manager --config ./config/custom.yaml --port 8080
./bin/validation-core --config ./config/custom.yaml --port 8081


##### Testing

1. Run unit tests:
bash
cd backend
go test ./tests/... -v


2. Run integration tests:
bash
cd backend
go test ./tests/integration_test.go -v


3. Run with coverage:
bash
cd backend
go test ./tests/... -v -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html


#### Full Stack Development
1. Build frontend first:
bash
npm run build


2. Start backend with GUI mode:
bash
cd backend
./dve-manager -gui
./validation-core -gui


3. Access the application:
- Frontend: http://localhost:3000 (development)
- GUI Mode: http://localhost:9080 (DVE Manager), http://localhost:9081 (Validation Core)
- API: http://localhost:8080 (DVE Manager), http://localhost:8081 (Validation Core)

๐Ÿ“ Project Structure




KNIRVNEXUS/
โ”œโ”€โ”€ src/ # Next.js Frontend
โ”‚ โ”œโ”€โ”€ app/ # Next.js App Router
โ”‚ โ”‚ โ”œโ”€โ”€ layout.tsx # Root layout
โ”‚ โ”‚ โ”œโ”€โ”€ page.tsx # Home page
โ”‚ โ”‚ โ”œโ”€โ”€ globals.css # Global styles
โ”‚ โ”‚ โ””โ”€โ”€ api/ # API routes
โ”‚ โ”œโ”€โ”€ components/ # React components
โ”‚ โ”‚ โ””โ”€โ”€ ui/ # shadcn/ui components
โ”‚ โ”œโ”€โ”€ hooks/ # Custom React hooks
โ”‚ โ”‚ โ”œโ”€โ”€ use-knirv-socket.ts # Socket.io integration
โ”‚ โ”‚ โ”œโ”€โ”€ use-mobile.ts # Mobile detection
โ”‚ โ”‚ โ””โ”€โ”€ use-toast.ts # Toast notifications
โ”‚ โ””โ”€โ”€ lib/ # Utility libraries
โ”‚ โ”œโ”€โ”€ db.ts # Database utilities
โ”‚ โ”œโ”€โ”€ socket.ts # Socket.io client
โ”‚ โ””โ”€โ”€ utils.ts # General utilities
โ”œโ”€โ”€ backend/ # Go backend services
โ”‚ โ”œโ”€โ”€ cmd/ # Service entry points
โ”‚ โ”‚ โ”œโ”€โ”€ dve-manager/ # DVE Manager service
โ”‚ โ”‚ โ””โ”€โ”€ validation-core/ # Validation Core service
โ”‚ โ”œโ”€โ”€ internal/ # Internal packages
โ”‚ โ”‚ โ”œโ”€โ”€ config/ # Configuration management
โ”‚ โ”‚ โ”œโ”€โ”€ database/ # BuntDB wrapper
โ”‚ โ”‚ โ”œโ”€โ”€ models/ # Data models
โ”‚ โ”‚ โ””โ”€โ”€ services/ # Business logic services
โ”‚ โ”œโ”€โ”€ pkg/ # Public packages
โ”‚ โ”‚ โ”œโ”€โ”€ p2p/ # P2P networking
โ”‚ โ”‚ โ””โ”€โ”€ sse/ # Server-Sent Events
โ”‚ โ”œโ”€โ”€ tests/ # Test suites
โ”‚ โ””โ”€โ”€ Dockerfile.* # Container definitions
โ”œโ”€โ”€ k8s/ # Kubernetes manifests
โ”‚ โ”œโ”€โ”€ namespace.yaml # Namespace and quotas
โ”‚ โ”œโ”€โ”€ configmap.yaml # Configuration
โ”‚ โ”œโ”€โ”€ secrets.yaml # Secrets management
โ”‚ โ””โ”€โ”€ *-deployment.yaml # Service deployments
โ”œโ”€โ”€ scripts/ # Automation scripts
โ”‚ โ”œโ”€โ”€ build.sh # Build automation
โ”‚ โ””โ”€โ”€ deploy.sh # Deployment automation
โ”œโ”€โ”€ public/ # Static assets
โ”‚ โ”œโ”€โ”€ logo.svg # KNIRV logo
โ”‚ โ””โ”€โ”€ robots.txt # SEO configuration
โ”œโ”€โ”€ prisma/ # Database schema
โ”‚ โ””โ”€โ”€ schema.prisma # Prisma schema definition
โ”œโ”€โ”€ config/ # Configuration files
โ”‚ โ”œโ”€โ”€ knirv-nexus.yaml # Main configuration
โ”‚ โ”œโ”€โ”€ development.yaml # Development config
โ”‚ โ””โ”€โ”€ production.yaml # Production config
โ”œโ”€โ”€ package.json # Frontend dependencies
โ”œโ”€โ”€ next.config.ts # Next.js configuration
โ”œโ”€โ”€ tailwind.config.ts # Tailwind CSS configuration
โ”œโ”€โ”€ components.json # shadcn/ui configuration
โ”œโ”€โ”€ server.ts # Custom server with Socket.io
โ”œโ”€โ”€ tsconfig.json # TypeScript configuration
โ””โ”€โ”€ README.md # This file


๐Ÿ”ง API Documentation



> Note: KNIRV-NEXUS APIs are accessed through the primary KNIRVGATEWAY at /api/nexus/* endpoints. Direct service access is available for development and internal communication.

Direct Service APIs



KNIRV-NEXUS exposes two main services with direct API access:

#### DVE Manager Service (Port 8080)

bash

Health check


curl -X GET http://dve-manager:8080/health

Register a new DVE node


curl -X POST http://dve-manager:8080/api/v1/nodes \
-H "Content-Type: application/json" \
-d '{
"name": "validator-1",
"tee_type": "sgx",
"stake_amount": 1000000,
"location": "us-east-1",
"ip_address": "192.168.1.100",
"public_key": "...",
"capabilities": ["skillnode", "base_llm"]
}'

List DVE nodes


curl -X GET http://dve-manager:8080/api/v1/nodes

System health


curl -X GET http://dve-manager:8080/api/v1/system/health


#### Validation Core Service (Port 8081)

bash

Health check


curl -X GET http://validation-core:8081/health

Create validation task


curl -X POST http://validation-core:8081/api/v1/tasks \
-H "Content-Type: application/json" \
-d '{
"type": "skillnode",
"priority": 5,
"skill_code": "def hello(): return \"Hello, World!\"",
"test_cases": [...],
"required_tee_type": "sgx"
}'

List validation tasks


curl -X GET http://validation-core:8081/api/v1/tasks

Get validation results


curl -X GET http://validation-core:8081/api/v1/results


Gateway Integration



For production use, access KNIRV-NEXUS through KNIRVGATEWAY:

bash

Via KNIRVGATEWAY (Production)


curl -X GET https://gateway.knirv.network/api/nexus/nodes
curl -X POST https://gateway.knirv.network/api/nexus/tasks

Real-time updates via SSE


const eventSource = new EventSource('https://gateway.knirv.network/api/nexus/sse');
eventSource.addEventListener('nexus-nodes', function(event) {
const data = JSON.parse(event.data);
console.log('Node update:', data);
});


๐Ÿ”ง Operational Modes



KNIRV-NEXUS supports two operational modes for different deployment scenarios:

Headless Mode (Default - Production)



Use Case: Production deployments, Kubernetes clusters, cloud environments

bash

Default headless mode


./dve-manager
./validation-core

With configuration file


./dve-manager --config ./config/production.yaml


Characteristics:
- API-only access (no web interface)
- Full JWT authentication required
- Binds to all network interfaces (0.0.0.0)
- Production-optimized resource usage
- Comprehensive audit logging
- Kubernetes-ready with health checks

GUI Mode (Local Administration)



Use Case: Local development, system administration, debugging

bash

Enable GUI mode


./dve-manager -gui
./validation-core -gui

With custom configuration


./dve-manager -gui --config ./config/development.yaml


Characteristics:
- Built-in web interface using existing Next.js frontend
- No authentication required (admin environment assumed)
- Localhost-only access (127.0.0.1)
- Real-time updates via WebSocket
- Extended debugging and diagnostic tools
- Direct access to configuration management

GUI Access:
- DVE Manager GUI: http://localhost:9080
- Validation Core GUI: http://localhost:9081
- API Access: http://localhost:8080, http://localhost:8081

Mode Comparison



| Feature | Headless Mode | GUI Mode |
|---------|---------------|----------|
| Target Use | Production | Local admin |
| Authentication | JWT required | None |
| Web Interface | None | Built-in Next.js frontend |
| Network Access | All interfaces | Localhost only |
| Resource Usage | Minimal | Higher (includes web server) |
| Security | Full RBAC + audit | Local access only |

โš™๏ธ Configuration



Configuration Management (Viper)



KNIRV-NEXUS uses Viper for professional configuration management with the following hierarchy (highest to lowest precedence):

1. CLI Flags: --gui, --port, --config
2. Environment Variables: KNIRV_GUI_ENABLED, KNIRV_SERVICE_PORT
3. Configuration File: config/knirv-nexus.yaml
4. Default Values: Hardcoded sensible defaults

Configuration File Structure



yaml

config/knirv-nexus.yaml


mode: headless # headless | gui

service:
port: 8080
bind_address: "0.0.0.0"
name: "dve-manager"

gui:
enabled: false
port: 9080
frontend_path: "./dist"

security:
auth_required: true
tls_enabled: true
audit_logging: true
jwt_secret: "${KNIRV_JWT_SECRET}"

roles:
validator:
permissions: ["node:read", "node:update", "tasks:read", "results:read"]
scoped_access: true
admin:
permissions: [":"]
scoped_access: false
observer:
permissions: ["*:read"]
scoped_access: false

database:
type: "buntdb"
path: "./data/nexus.db"

network:
chain_id: "knirv-nexus-mainnet"
p2p_port: 4001


Environment Variables



| Variable | Description | Default |
|----------|-------------|---------|
| KNIRV_MODE | Operational mode | headless |
| KNIRV_GUI_ENABLED | Enable GUI mode | false |
| KNIRV_SERVICE_PORT | API server port | 8080 |
| KNIRV_GUI_PORT | GUI server port | 9080 |
| KNIRV_CHAIN_ID | Blockchain network ID | knirv-nexus-mainnet |
| KNIRV_DATABASE_PATH | Database file path | ./data/nexus.db |
| KNIRV_P2P_PORT | P2P networking port | 4001 |
| KNIRV_LOG_LEVEL | Logging level | info |
| KNIRV_JWT_SECRET | JWT signing secret | Required |

Kubernetes Configuration



Key configuration files:

- k8s/namespace.yaml: Namespace and resource quotas
- k8s/configmap.yaml: Application configuration
- k8s/secrets.yaml: Sensitive configuration (JWT secrets, TLS certs)
- k8s/*-deployment.yaml: Service deployments

๐Ÿ”’ Security



TEE Support



KNIRV-NEXUS supports multiple TEE technologies:

- Intel SGX: Hardware-based secure enclaves
- AMD SEV-SNP: Secure encrypted virtualization
- Intel TDX: Trust domain extensions
- Software TEE: Simulation for development/testing

Network Security



- P2P Encryption: All P2P communications are encrypted
- TLS Termination: HTTPS/TLS for all API endpoints
- JWT Authentication: Secure token-based authentication
- RBAC: Role-based access control

Container Security



- Rootless Containers: Podman-based rootless execution
- Minimal Base Images: Hardened Kali Linux base
- Security Scanning: Automated vulnerability scanning
- Network Policies: Kubernetes network isolation

๐Ÿ“Š Monitoring and Observability



Metrics



KNIRV-NEXUS exposes Prometheus metrics on /metrics endpoints:

- System health and performance metrics
- DVE node status and resource utilization
- Validation task throughput and success rates
- P2P network topology and latency

Logging



Structured JSON logging with configurable levels:

bash

View logs


kubectl logs -f deployment/api-gateway -n knirv-nexus
kubectl logs -f deployment/dve-manager -n knirv-nexus
kubectl logs -f deployment/validation-core -n knirv-nexus


Health Checks



All services provide health check endpoints:

- GET /health: Basic health status
- Kubernetes liveness and readiness probes
- Automatic service recovery and scaling

๐Ÿงช Testing



The implementation includes comprehensive testing:

- Unit Tests: Individual component testing
- Integration Tests: End-to-end service testing
- Performance Tests: Validation throughput benchmarks
- Security Tests: Vulnerability scanning

Run tests with:
bash
cd backend
go test ./tests/... -v


๐Ÿ› ๏ธ Troubleshooting



Common Backend Issues



#### 1. JWT Secret Configuration Error
Error: Failed to load configuration: invalid configuration: security.jwt_secret is required in headless mode with authentication

Causes & Solutions:
- Environment variable not set:
bash
# Set JWT_SECRET environment variable
export JWT_SECRET="your-secure-jwt-secret-here"

# Or use development environment
cp .env.development .env
export $(cat .env | xargs)


- Using GUI mode but auth still required:
bash
# Use development environment for GUI mode
export KNIRV_MODE=gui
export KNIRV_AUTH_REQUIRED=false

# Or run with GUI flag
./bin/dve-manager --gui


- Shell variable expansion issue in .env file:
bash
# Instead of KNIRV_JWT_SECRET=${JWT_SECRET}
# Use direct value: KNIRV_JWT_SECRET=your-actual-secret


#### 2. Build Failures
Error: go build fails with dependency issues

Solutions:
bash
cd backend

Clean module cache


go clean -modcache

Update dependencies


go mod tidy

Verify dependencies


go mod verify

Build with verbose output


go build -v ./cmd/dve-manager/


#### 3. Database Connection Issues
Error: Database path not accessible

Solutions:
bash

Create data directory


mkdir -p data

Check permissions


chmod 755 data

Use absolute path in config


export KNIRV_DATABASE_PATH="$(pwd)/data/nexus.db"


#### 4. Port Already in Use
Error: bind: address already in use

Solutions:
bash

Check what's using the port


lsof -i :8080

Kill process using port


kill -9 $(lsof -t -i:8080)

Use different port


./bin/dve-manager --port 8081


#### 5. P2P Network Issues
Error: P2P connection failures

Solutions:
bash

Check firewall


sudo ufw status

Allow P2P port


sudo ufw allow 4001

Check if port is accessible


nc -zv localhost 4001


Configuration Troubleshooting



#### Environment Variable Priority
Configuration is loaded in this order (highest to lowest priority):
1. CLI flags: --gui, --port, --config
2. Environment variables: KNIRV_*
3. Configuration file: config/knirv-nexus.yaml
4. Default values

#### Debug Configuration Loading
bash

Enable debug logging


export KNIRV_LOG_LEVEL=debug

Run with verbose output


./bin/dve-manager --gui 2>&1 | grep -i config


#### Validate Configuration
bash

Test configuration without starting service


./bin/dve-manager --config ./config/development.yaml --help


Development Environment Issues



#### 1. Go Version Compatibility
Error: Build fails with Go version issues

Solutions:
bash

Check Go version


go version

Should be 1.21+


Update Go if needed


sudo rm -rf /usr/local/go
wget https://golang.org/dl/go1.21.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz


#### 2. CGO Dependencies
Error: CGO compilation fails

Solutions:
bash

Install build essentials


sudo apt-get update
sudo apt-get install build-essential

For static builds


sudo apt-get install musl-dev


Kubernetes Deployment Issues



1. Pod startup failures: Check resource limits and node capacity
2. P2P connectivity issues: Verify firewall rules and port accessibility
3. Database errors: Check persistent volume availability
4. Authentication failures: Verify JWT secret configuration in secrets

Debug Commands



bash

Check pod status


kubectl get pods -n knirv-nexus -o wide

View pod logs


kubectl logs -f pod/ -n knirv-nexus

Execute into pod


kubectl exec -it pod/ -n knirv-nexus -- /bin/bash

Check service endpoints


kubectl get endpoints -n knirv-nexus

View events


kubectl get events -n knirv-nexus --sort-by='.lastTimestamp'


๐Ÿค Contributing



1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite: go test ./tests/... -v
6. Submit a pull request

๐Ÿ“„ License



This project is part of the KNIRV Network and follows the project's licensing terms.

๐Ÿ†˜ Support



For support and questions:

- Create an issue in the GitHub repository
- Join the KNIRV Network community discussions
- Review the technical documentation in the codebase

Built with โค๏ธ for the developer community. Supercharged by Z.ai ๐Ÿš€