Skip to content

development-setup.md

Latest commit

 

History

History
690 lines (534 loc) · 15.3 KB

development-setup.md

File metadata and controls

690 lines (534 loc) · 15.3 KB

SentinelAI Development Environment Setup

Complete guide for setting up a local development environment for SentinelAI, covering all prerequisites, local Kubernetes options, and development workflows.

Table of Contents

Prerequisites

System Requirements

Minimum Requirements

  • CPU: 4 cores
  • Memory: 8GB RAM
  • Storage: 20GB free space
  • OS: macOS, Linux, or Windows with WSL2

Recommended Requirements

  • CPU: 8 cores
  • Memory: 16GB RAM
  • Storage: 50GB free space (SSD recommended)
  • Network: Stable internet connection for image downloads

Required Software

Core Development Tools

  1. Go (1.21+)

    # macOS
brew install go

# Linux
wget https://go.dev/dl/go1.21.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

# Windows (WSL2)
wget https://go.dev/dl/go1.21.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.linux-amd64.tar.gz

  2. Node.js (18+)

    # Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# macOS with Homebrew
brew install node@18

# Linux package manager
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

  3. Git

    # macOS
brew install git

# Linux
sudo apt-get install git

# Configure Git
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Container and Kubernetes Tools

  1. Docker Desktop

    • Download from docker.com
    • Enable Kubernetes in Docker Desktop settings
    • Allocate minimum 8GB RAM and 4 CPU cores

  2. kubectl

    # macOS
brew install kubectl

# Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# Verify installation
kubectl version --client

  3. Helm 3

    # macOS
brew install helm

# Linux
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Verify installation
helm version

Optional Tools

  1. GitHub CLI (Recommended)

    # macOS
brew install gh

# Linux
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

# Authenticate
gh auth login

  2. IDE/Editor Setup

    • VS Code with Go and React extensions
    • GoLand for comprehensive Go development
    • WebStorm for frontend development

Quick Start

Automated Setup

# Clone SentinelAI repository
git clone https://github.com/your-username/SentinelAI.git
cd SentinelAI

# Copy environment template and configure
cp .env.example .env
# Edit .env with your settings

# Run complete setup
make setup

This automated setup will:

  1. Fork and clone SigNoz repository
  2. Set up local Kubernetes cluster
  3. Deploy SigNoz for baseline testing
  4. Configure development environment

Manual Setup Steps

If you prefer manual setup or need to troubleshoot:

# 1. Fork and clone SigNoz
./scripts/fork-signoz.sh

# 2. Set up local Kubernetes
./scripts/setup-local-k8s.sh

# 3. Deploy SigNoz for development
./scripts/deploy-signoz-dev.sh

Local Kubernetes Options

Docker Desktop (Recommended for Mac/Windows)

Setup

  1. Install Docker Desktop
  2. Enable Kubernetes in Settings → Kubernetes
  3. Allocate resources in Settings → Resources:
    • Memory: 8GB minimum
    • CPUs: 4 minimum
    • Swap: 2GB
    • Disk: 64GB

Verification

# Check Docker Desktop context
kubectl config current-context
# Should show: docker-desktop

# Verify cluster
kubectl cluster-info
kubectl get nodes

Configuration for SentinelAI

# Verify default StorageClass
kubectl get storageclass
# Should show 'hostpath' as default

# If needed, set default StorageClass
kubectl patch storageclass hostpath -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

Minikube (Cross-platform)

Installation

# macOS
brew install minikube

# Linux
curl -Lo minikube https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube /usr/local/bin/

Setup for SentinelAI

# Start with adequate resources
minikube start \
  --memory=8g \
  --cpus=4 \
  --disk-size=20g \
  --kubernetes-version=stable

# Enable required addons
minikube addons enable default-storageclass
minikube addons enable storage-provisioner

# Verify setup
kubectl get nodes
kubectl get storageclass

Useful Minikube Commands

# Check status
minikube status

# Access dashboard
minikube dashboard

# Get cluster IP for services
minikube service list

# SSH into minikube
minikube ssh

# Stop/Delete cluster
minikube stop
minikube delete

kind (Lightweight Alternative)

Installation

# macOS
brew install kind

# Linux
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

Setup with Custom Configuration

# Create cluster with SentinelAI configuration
kind create cluster --name sentinelai-dev --config kubernetes/local/kind-config.yaml

# If config file doesn't exist, create basic cluster
kind create cluster --name sentinelai-dev

# Set context
kubectl config use-context kind-sentinelai-dev

kind Configuration (kubernetes/local/kind-config.yaml)

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: sentinelai-dev
nodes:
- role: control-plane
  kubeadmConfigPatches:
  - |
    kind: InitConfiguration
    nodeRegistration:
      kubeletExtraArgs:
        node-labels: "ingress-ready=true"
  extraPortMappings:
  - containerPort: 80
    hostPort: 8080
    protocol: TCP
  - containerPort: 443
    hostPort: 8443
    protocol: TCP
  - containerPort: 3301
    hostPort: 3301
    protocol: TCP
- role: worker

Development Tools Setup

IDE Configuration

VS Code Setup

# Install VS Code extensions
code --install-extension golang.go
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension ms-kubernetes-tools.vscode-kubernetes-tools
code --install-extension ms-vscode.docker

# Workspace settings (.vscode/settings.json)
{
  "go.useLanguageServer": true,
  "go.gocodeAutoBuild": true,
  "typescript.preferences.quoteStyle": "double",
  "kubernetes.kubectl-path": "/usr/local/bin/kubectl"
}

Go Development Environment

# Install useful Go tools
go install golang.org/x/tools/gopls@latest
go install github.com/go-delve/delve/cmd/dlv@latest
go install golang.org/x/tools/cmd/goimports@latest

# Configure Go environment
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin

Frontend Development Setup

# Navigate to SigNoz frontend directory
cd signoz/frontend

# Install dependencies
npm install

# Install additional development tools
npm install -g @typescript-eslint/eslint-plugin
npm install -g prettier

# Configure Prettier
echo '{
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "quoteProps": "as-needed",
  "trailingComma": "es5"
}' > .prettierrc

Database Tools

ClickHouse Client

# macOS
brew install clickhouse

# Linux
sudo apt-get install apt-transport-https ca-certificates dirmngr
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv E0C56BD4
echo "deb https://repo.clickhouse.tech/deb/stable/ main/" | sudo tee /etc/apt/sources.list.d/clickhouse.list
sudo apt-get update
sudo apt-get install clickhouse-client

# Connect to local ClickHouse (after deployment)
clickhouse-client --host localhost --port 9000

Database GUI Tools

  • DBeaver: Universal database client
  • ClickHouse Tabix: Web-based ClickHouse interface
  • DataGrip: JetBrains database IDE

SigNoz Fork Setup

Understanding the Fork Structure

After running ./scripts/fork-signoz.sh, you'll have:

SentinelAI/
├── signoz/                     # Forked SigNoz repository
│   ├── cmd/                    # Main applications
│   ├── pkg/                    # Core packages
│   ├── frontend/               # React frontend
│   ├── deploy/                 # Deployment configs
│   └── ...
├── scripts/                    # SentinelAI automation
├── docs/                       # SentinelAI documentation
└── kubernetes/                 # Local development configs

Working with the Fork

Branch Strategy

cd signoz

# Main development branch
git checkout sentinelai-develop

# Create feature branches
git checkout -b feature/multi-tenant-auth
git checkout -b feature/ai-insights
git checkout -b feature/smb-dashboards

# Sync with upstream
git fetch upstream
git checkout sentinelai-develop
git merge upstream/main

Development Workflow

# Make changes in the signoz/ directory
cd signoz

# Backend changes
# Edit files in pkg/, cmd/, etc.

# Frontend changes
cd frontend
npm start  # Start development server

# Test changes
cd ..
go test ./...

# Build and test locally
docker build -t sentinelai-local .

Development Workflow

Daily Development Process

1. Environment Startup

# Start local Kubernetes (if not running)
minikube start  # or use Docker Desktop

# Check cluster status
kubectl cluster-info

# Start SigNoz if needed
make deploy-dev

2. Development Loop

# Navigate to SigNoz directory
cd signoz

# Start frontend development server
cd frontend
npm start

# In another terminal, work on backend
cd ../
# Make changes to Go code

# Test changes
go test ./pkg/...

# Build and restart services as needed
kubectl rollout restart deployment/signoz-frontend -n sentinelai-dev

3. Testing and Validation

# Run unit tests
go test ./...

# Run frontend tests
cd frontend
npm test

# Integration testing
kubectl get pods -n sentinelai-dev
kubectl logs -f deployment/signoz-frontend -n sentinelai-dev

# Access application
open http://localhost:3301

Debugging

Backend Debugging

# Enable debug logging
export LOG_LEVEL=debug

# Use delve for debugging
cd signoz
dlv debug ./cmd/...

# Remote debugging in Kubernetes
kubectl port-forward pod/signoz-backend-xxx 2345:2345
dlv connect localhost:2345

Frontend Debugging

# React Developer Tools browser extension
# Browser DevTools for network and performance
# VS Code debugger configuration

# .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Launch Chrome against localhost",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}/signoz/frontend/src"
    }
  ]
}

Database Debugging

# Connect to ClickHouse
kubectl port-forward svc/clickhouse 9000:9000 -n sentinelai-dev
clickhouse-client --host localhost --port 9000

# Query tenant data
SELECT tenantID, count() FROM distributed_traces_tenant GROUP BY tenantID;

# Check table structure
DESCRIBE distributed_traces_tenant;

Performance Optimization

Local Development Optimizations

# Reduce resource requests in values-dev.yaml
# Use local Docker registry for faster image pulls
# Enable hot reload for frontend development

# Frontend hot reload
cd signoz/frontend
npm start -- --host 0.0.0.0 --port 3000

# Backend hot reload with air
go install github.com/cosmtrek/air@latest
air -c .air.toml

Resource Monitoring

# Monitor cluster resources
kubectl top nodes
kubectl top pods -n sentinelai-dev

# Monitor specific services
kubectl logs -f deployment/signoz-backend -n sentinelai-dev
kubectl describe pod signoz-clickhouse-xxx -n sentinelai-dev

Troubleshooting

Common Issues

1. Kubernetes Cluster Issues

Issue: Cluster not starting or pods stuck in pending

# Check cluster status
kubectl cluster-info
kubectl get nodes

# Check events
kubectl get events --sort-by='.lastTimestamp'

# Check resource usage
kubectl top nodes
kubectl describe node <node-name>

# Solution: Increase cluster resources or restart cluster
minikube stop && minikube start --memory=8g --cpus=4

2. Storage Issues

Issue: Persistent volumes not mounting

# Check StorageClass
kubectl get storageclass

# Check PVC status
kubectl get pvc -n sentinelai-dev

# Solution: Ensure default StorageClass is set
kubectl patch storageclass <storage-class> -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

3. Port Forwarding Issues

Issue: Cannot access SigNoz UI

# Check services
kubectl get svc -n sentinelai-dev

# Manual port forwarding
kubectl port-forward svc/signoz-frontend 3301:3301 -n sentinelai-dev

# Check if ports are in use
lsof -i :3301
kill -9 <pid>  # if needed

4. Build Issues

Issue: Go build failures

# Check Go version
go version

# Clean module cache
go clean -modcache

# Update dependencies
cd signoz
go mod tidy
go mod download

Issue: Frontend build failures

# Check Node.js version
node --version
npm --version

# Clear npm cache
npm cache clean --force

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Getting Help

Debug Information Collection

# Collect cluster information
kubectl cluster-info dump > cluster-info.txt

# Collect pod logs
kubectl logs deployment/signoz-frontend -n sentinelai-dev > frontend.log
kubectl logs deployment/signoz-backend -n sentinelai-dev > backend.log

# Collect system information
uname -a > system-info.txt
docker version >> system-info.txt
kubectl version >> system-info.txt

Support Channels

Conclusion

This development setup guide provides a comprehensive foundation for SentinelAI development. The local Kubernetes environment enables full-stack development with realistic production-like conditions while maintaining fast iteration cycles.

Key success factors:

  1. Adequate Resources: Ensure sufficient CPU and memory allocation
  2. Tool Familiarity: Invest time in learning kubectl and debugging tools
  3. Incremental Development: Test changes frequently in the local environment
  4. Documentation: Keep notes on customizations and integration points
  5. Community Engagement: Leverage both SigNoz and broader Kubernetes communities

With this setup, you're ready to develop powerful SentinelAI enhancements while maintaining compatibility with the robust SigNoz foundation.