flowfish/docs/QUICK_START.md

Flowfish - Quick Start Guide

Get Flowfish up and running in 10 minutes!

⚡ Prerequisites

• Kubernetes 1.27+ or OpenShift 4.13+
• kubectl/oc configured and connected to your cluster
• 16GB RAM, 4 CPU cores available
• (Optional) Helm 3.x for Helm installation

🚀 Installation Steps

Step 1: Deploy Flowfish (2 minutes)

# Clone repository
git clone https://github.com/yourusername/flowfish.git
cd flowfish

# Deploy to Kubernetes
kubectl apply -f deployment/kubernetes-manifests/

Step 2: Wait for Pods (3-5 minutes)

# Watch pods starting
kubectl get pods -n flowfish -w

# All pods should be "Running" and "Ready"
# Expected pods:
# - frontend (2 replicas)
# - backend (3 replicas)
# - postgresql (1 replica)
# - redis (1 replica)
# - clickhouse (3 replicas)
# - neo4j (1 replica)
# - inspektor-gadget (DaemonSet, 1 per node)

Step 3: Access UI (1 minute)

# Port-forward frontend service
kubectl port-forward svc/frontend -n flowfish 3000:3000

# Open browser
open http://localhost:3000

Login Credentials:

• Username: admin
• Password: admin123

⚠️ Important: Change password after first login!

🎯 First Steps After Login

1. Add Your First Cluster (2 minutes)

Prerequisites:

• The cluster-manager service must be running (included in Docker Compose by default)
• For remote clusters (not the cluster Flowfish is deployed on): run the Setup Script on the target cluster first. Navigate to Add Cluster → Setup Script tab to generate the script for your provider. This installs Inspektor Gadget and creates the required ServiceAccount/RBAC.

Navigate to Management → Cluster Management → Add Cluster

Fill in details:

• Name: my-first-cluster
• Type: kubernetes or openshift
• API URL: Your cluster API URL (e.g., https://api.cluster.example.com:6443)
• Authentication: Upload kubeconfig or paste service account token

Click Save. Flowfish will connect and start discovering workloads.

Troubleshooting: If pods/nodes/namespaces show 0 after adding a cluster:

• Check cluster-manager logs: docker logs flowfish-cluster-manager (Docker Compose) or kubectl logs -l app=cluster-manager -n flowfish (Kubernetes)
• Verify the Setup Script was run on the target cluster
• Ensure FLOWFISH_ENCRYPTION_KEY is the same for both backend and cluster-manager services

2. Create Your First Analysis (3 minutes)

Navigate to Analysis → Create New

Step 1: Scope

• Select: Namespace
• Choose 1-2 namespaces to analyze (start small!)

Step 2: Gadgets

• ✅ Network Traffic (TCP/UDP)
• ✅ DNS Queries
• ☐ Leave others unchecked for now

Step 3: Time

• Select: Continuous (runs until you stop it)

Step 4: Output

• ✅ Application Dependency Dashboard
• ☐ LLM Analysis (skip for now)

Click "Create Analysis"

3. Start Analysis (< 1 minute)

• Go to Analysis List
• Find your analysis
• Click Start button
• Wait 30-60 seconds for data collection to begin

4. View Live Map (Instant!)

Navigate to Discovery → Live Map

You should see:

• Nodes: Your pods, deployments, services
• Edges: Communication flows between them
• Live updates: New connections appearing in real-time

Try This:

• Click a node → See details in right panel
• Drag nodes → Reposition manually
• Use filters → Filter by namespace or risk level
• Change layout → Try "Hierarchical" or "Force-directed"

🎉 Success!

You now have Flowfish running and analyzing your cluster!

🚀 Next Steps

Explore Dashboards

1. Overview Dashboard - See system metrics, top services, risk distribution
2. Traffic Dashboard - Analyze traffic patterns and protocols
3. Security Dashboard - View risk scores and security alerts

Enable Advanced Features

Add LLM for Anomaly Detection

1. Go to Management → Integration Settings → LLM Configuration
2. Add your OpenAI API key
3. Enable anomaly detection
4. Set frequency (e.g., every 15 minutes)

Configure Webhooks

1. Go to Management → Integration Settings → Webhooks
2. Add webhook URL (Slack, Teams, or custom)
3. Select event types (anomaly detected, change detected)
4. Test webhook

Create a Baseline

Creating a baseline helps detect anomalies by learning "normal" traffic.

1. Go to Analysis → Create New
2. Step 3: Select Baseline Creation Mode
3. Duration: 7 days recommended
4. Start analysis and let it run for a week

After 7 days:

• Go to Data → Baseline Management
• View your baseline
• Enable anomaly detection (compares current traffic to baseline)

📚 Learn More

• User Manual: docs/user-manual.md
• Analysis Wizard Guide: docs/analysis-wizard.md
• Dashboard Guide: docs/dashboards.md
• API Documentation: http://localhost:8000/api/docs

🐛 Troubleshooting

UI not loading?

# Check frontend pod
kubectl logs -l app=frontend -n flowfish

No data in Live Map?

# Check if analysis is running
kubectl logs -l app=backend -n flowfish | grep "analysis"

# Check Inspektor Gadget
kubectl logs -l app=inspektor-gadget -n gadget

Can't connect to cluster?

• Verify API URL is correct
• Check kubeconfig/token has proper permissions
• Test with: kubectl cluster-info

💡 Tips

1. Start Small: Analyze 1-2 namespaces first, then expand
2. Watch Live Map: Keep it open to see real-time updates
3. Check Anomalies Daily: Review anomaly detection page regularly
4. Export Data: Backup your dependency maps regularly
5. Use Filters: Leverage namespace/type/risk filters for clarity

🎓 Training Resources

• Video Tutorial: YouTube: Flowfish Getting Started
• Webinar: Join our weekly community webinar
• Slack: Ask questions in #flowfish-support

---

Happy analyzing! 🐟🌊

Need help? Open an issue: GitHub Issues