dashboard/QUICKSTART.md

🚀 Quick Start Guide

Panduan cepat untuk menjalankan Dashboard Solusi AI Peternakan Ayam.

⚡ TL;DR - Super Quick Start

Opsi 1: Docker (Recommended for Production) 🐳

# 1. Install Docker & Docker Compose
# 2. Clone repository
git clone <repo-url>
cd dashboard-solusi-ai-peternakan-ayam

# 3. Deploy
docker-compose up -d --build

# 4. Access
# http://localhost

Opsi 2: Manual (For Development) 💻

# 1. Install dependencies
npm install
cd backend && npm install && cd ..

# 2. Terminal 1 - Start Backend
cd backend
npm run dev

# 3. Terminal 2 - Start Frontend
npm run dev

# 4. Open browser
# Frontend: http://localhost:3001
# Backend API: http://localhost:5001

---

🐳 Docker Deployment (Recommended)

Prerequisites

• ✅ Docker v20.10+ (Download)
• ✅ Docker Compose v2.0+ (Download)

Quick Deploy

# Clone repository
git clone <repo-url>
cd dashboard-solusi-ai-peternakan-ayam

# Create data directory
mkdir -p data

# Deploy
docker-compose up -d --build

# Check status
docker-compose ps

# View logs
docker-compose logs -f

Access: http://localhost or http://your-server-ip

📚 Complete Docker Guide: DOCKER.md

---

💻 Manual Installation

📋 Prerequisites

Pastikan sudah terinstall:

• ✅ Node.js v18+ (Download)
• ✅ npm v9+
• ✅ Port 3001 dan 5001 tersedia

Cek versi:

node --version  # Should be v18.0.0 or higher
npm --version   # Should be v9.0.0 or higher

---

📦 Step 1: Install Dependencies

Frontend Dependencies

npm install

Backend Dependencies

cd backend
npm install
cd ..

Troubleshooting:

• Jika error EACCES: Gunakan sudo npm install atau fix npm permissions
• Jika error node-gyp: Install build tools untuk OS Anda

---

▶️ Step 2: Start Backend Server

Buka Terminal 1:

cd backend
npm run dev

✅ Output yang benar:

========================================
🚀 Server running on http://localhost:5001
========================================

API Endpoints:
  GET    /health
  GET    /api/cycles
  GET    /api/cycles/active
  ...

✓ Database initialized successfully

❌ Jika gagal:

Problem: Port 5001 sudah terpakai

# Check what's using port 5001
lsof -i :5001

# Solution: Change port in backend/.env
PORT=5002

Problem: Database error

# Make sure PostgreSQL is running
# For local development, check backend/.env for DB credentials
cd backend
node database/seed-postgres.js

---

▶️ Step 3: Start Frontend Server

Buka Terminal 2 (baru):

npm run dev

✅ Output yang benar:

VITE v6.4.1  ready in 155 ms

➜  Local:   http://localhost:3001/
➜  Network: http://127.0.2.2:3001/

Note: Jika port 3001 terpakai, Vite akan otomatis menggunakan port lain (misalnya 3002).

---

🌐 Step 4: Open in Browser

Buka browser dan akses:

Frontend Dashboard:

http://localhost:3001

Backend API (optional):

http://localhost:5001/health

---

✅ Verify Installation

Test 1: Backend Health Check

curl http://localhost:5001/health

Expected response:

{ "status": "ok", "timestamp": "2025-12-22T03:02:20.793Z" }

Test 2: Get Cycles Data

curl http://localhost:5001/api/cycles

Expected response:

{
  "success": true,
  "data": [
    {
      "id": "CYCLE-JBW-2025-12-10",
      "totalDays": 42,
      "currentDay": 7,
      "startDate": "2025-12-10",
      "endDate": "2026-01-20",
      "docInCount": 20000,
      "status": "Active",
      ...
    }
  ]
}

Test 3: Frontend Loads

1. Open http://localhost:3001
2. You should see the dashboard with:
   • ✅ KPI cards (Population, Mortality, etc.)
   • ✅ Linimasa Siklus sidebar menu
   • ✅ No console errors (press F12)

Test 4: Database Integration

1. Navigate to "Linimasa Siklus Produksi"
2. Click "Edit" on active cycle
3. Change DOC In count: 20000 → 21000
4. Click "Simpan"
5. Refresh page (F5)
6. ✅ Data should persist - DOC count still shows 21000

---

📚 Next Steps

Explore Features

1. Dashboard Utama - View KPI and real-time monitoring
2. Linimasa Siklus - Manage production cycles
3. Hitung Ayam > Manajemen Data - Edit mortality data
4. Monitoring Berat - View weight distribution
5. Standar Performa - Compare with Cobb standards

Test Database Persistence

Test Mortality Data:

1. Go to "Hitung Ayam" > "Manajemen Data"
2. Click "Edit" on any day
3. Change mortality value
4. Click save (✓)
5. Refresh page - data should persist

---

🔧 Common Issues

Issue: "Cannot connect to backend"

Symptoms:

• Frontend shows no data
• Console shows: Failed to load cycles from database

Solution:

1. Check backend is running: curl http://localhost:5001/health
2. Check CORS settings in backend/server.js
3. Check frontend API URL in services/apiService.ts:

   const DB_API_BASE_URL = 'http://localhost:5001/api';
   

Issue: "Port already in use"

Backend (5001):

# Find process using port 5001
lsof -i :5001

# Kill the process (replace PID)
kill -9 <PID>

# Or change port in backend/.env

Frontend (3001):

• Vite will auto-select another port
• Check terminal output for actual port

Issue: "Database not found" or "Connection refused"

# Make sure PostgreSQL is running locally
# Check connection settings in backend/.env:
# DB_HOST=localhost
# DB_PORT=5432
# DB_USER=dashboard_user
# DB_PASSWORD=your_password
# DB_NAME=dashboard_db

cd backend
node database/seed-postgres.js
npm run dev

Issue: "Module not found"

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

# Backend
cd backend
rm -rf node_modules package-lock.json
npm install

---

🛑 Stopping Servers

Stop Backend:

# In backend terminal, press:
Ctrl + C

Stop Frontend:

# In frontend terminal, press:
Ctrl + C

Kill All Node Processes (if stuck):

# macOS/Linux
killall node

# Windows
taskkill /F /IM node.exe

---

📖 Full Documentation

For detailed documentation, see:

• README.md - Complete project documentation
• backend/README.md - Backend API documentation
• API Endpoints - http://localhost:5001 (when server is running)

---

💡 Tips

1. Keep both terminals open - Don't close backend and frontend terminals
2. Check logs - Backend logs show all API requests and SQL queries
3. Use browser DevTools - F12 to see network requests and errors
4. Database is PostgreSQL - Connection details in backend/.env
5. Auto-reload - Both frontend and backend support hot reload
6. Local database guide - See docs/LOCAL_DATABASE_GUIDE.md for syncing with production

---

✨ Features Quick Reference

Feature	Location	Description
View Cycles	Linimasa Siklus	See all production cycles
Edit Cycle	Linimasa > Edit	Modify dates, DOC count
Mortality Data	Hitung Ayam > Manajemen Data	CRUD mortality records
Weight Stats	Monitoring Berat	View weight distribution
Cobb Standards	Standar Performa	Compare with standards

---

🎯 Success Checklist

• Backend running on port 5001
• Frontend running on port 3001
• /health endpoint returns {"status":"ok"}
• /api/cycles returns 4 cycles
• Dashboard loads in browser
• Can edit cycle data and it persists
• Can edit mortality data and it persists
• No errors in browser console
• No errors in backend logs

---

Ready to go! 🚀

If you encounter any issues not covered here, check the full README.md or backend/README.md.