innotexBoard/QUICKSTART.md

# 📖 Guide de Démarrage - InnotexBoard

## 🎯 Objectif

Ce guide vous aide à démarrer avec InnotexBoard en 5 minutes.

---

## 1️⃣ Installation rapide (Mode développement)

### Backend

```bash
# Aller dans le dossier backend
cd backend

# Créer un environnement virtuel
python3 -m venv venv
source venv/bin/activate  # Sur Windows: venv\Scripts\activate

# Installer les dépendances
pip install -r requirements.txt

# Copier la configuration
cp .env.example .env

# Lancer le serveur
python main.py
```

✅ Le serveur tourne sur `http://localhost:8000`

Tester dans un autre terminal :
```bash
curl http://localhost:8000/health
```

### Frontend

```bash
# Dans un autre terminal, aller dans le dossier frontend
cd frontend

# Installer les dépendances
npm install

# Lancer le serveur de développement
npm run dev
```

✅ L'interface tourne sur `http://localhost:3000`

---

## 2️⃣ Configuration des permissions

### ⚠️ Important : Accès Docker et système

Pour que l'application fonctionne, le serveur Python a besoin d'accès à :

1. **Docker** - Pour contrôler les conteneurs
2. **PAM** - Pour authentifier les utilisateurs
3. **psutil** - Pour lire les stats système

### Option simple (Développement)

```bash
# Lancer le backend avec sudo
sudo python3 main.py

# OU ajouter l'utilisateur au groupe docker
sudo usermod -aG docker $USER
newgrp docker
```

### Option sécurisée (Production)

Voir [PERMISSIONS.md](../PERMISSIONS.md) pour une configuration complète.

---

## 3️⃣ Premier test de l'application

1. Ouvrir `http://localhost:3000` dans votre navigateur
2. Se connecter avec un utilisateur Debian existant
   - Exemple : votre utilisateur système
3. Voir le Dashboard avec CPU/RAM
4. Visiter l'onglet "Conteneurs Docker"

---

## 📝 Structure du code

### Backend

```
backend/
├── main.py                    # Point d'entrée FastAPI
├── requirements.txt           # Dépendances Python
├── app/
│   ├── core/
│   │   ├── config.py         # Configuration
│   │   └── security.py       # Authentification JWT/PAM
│   ├── api/
│   │   └── endpoints/
│   │       ├── auth.py       # Routes login
│   │       ├── system.py     # Routes CPU/RAM/processus
│   │       └── docker.py     # Routes Docker
│   └── services/
│       ├── system.py         # Logique psutil
│       └── docker_service.py # Logique Docker SDK
```

### Frontend

```
frontend/
├── src/
│   ├── main.js               # Point d'entrée Vue
│   ├── App.vue               # Composant racine
│   ├── api/
│   │   └── index.js          # Client HTTP Axios
│   ├── stores/
│   │   └── auth.js           # State Pinia (auth)
│   ├── router/
│   │   └── index.js          # Routes Vue Router
│   ├── views/
│   │   ├── LoginView.vue     # Écran connexion
│   │   ├── DashboardView.vue # Écran stats
│   │   └── ContainersView.vue# Écran Docker
│   └── assets/
│       └── styles.css        # Tailwind CSS
```

---

## 🧪 Tests basiques

### Tester l'API avec curl

```bash
# 1. Obtenir un token
TOKEN=$(curl -s -X POST "http://localhost:8000/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=your_user&password=your_pass" \
  | jq -r '.access_token')

# 2. Récupérer les stats
curl -X GET "http://localhost:8000/api/v1/system/stats" \
  -H "Authorization: Bearer $TOKEN"

# 3. Lister les conteneurs
curl -X GET "http://localhost:8000/api/v1/docker/containers" \
  -H "Authorization: Bearer $TOKEN"
```

### Tester dans le navigateur

1. Ouvrir `http://localhost:3000`
2. Entrer les identifiants d'un utilisateur système
3. Vérifier la connexion dans la console (F12)
4. Voir les logs du backend

---

## 🐛 Problèmes courants

### "Connection refused" (Backend)

```bash
# Vérifier que le backend tourne
curl http://localhost:8000/health

# Vérifier les ports
netstat -tulpn | grep 8000
```

### "Permission denied" (Docker)

```bash
# Option 1: Ajouter au groupe docker
sudo usermod -aG docker $USER
newgrp docker

# Option 2: Lancer avec sudo
sudo python3 main.py
```

### "Password authentication failed" (PAM)

```bash
# Vérifier que l'utilisateur existe
id your_user

# Vérifier PAM
python3 -c "import pam; print(pam.pam().authenticate('your_user', 'your_pass'))"
```

### "Cannot connect to Docker daemon"

```bash
# Vérifier que Docker tourne
sudo systemctl status docker

# Vérifier les permissions du socket
ls -la /var/run/docker.sock
```

---

## 📚 Modèle de composant Vue.js

Exemple pour créer une nouvelle page :

```vue
<template>
  <div class="p-8">
    <h1 class="text-3xl font-bold mb-8">Ma Nouvelle Page</h1>
    
    <div class="card">
      <h3 class="text-lg font-semibold mb-4">Contenu</h3>
      <p>{{ data }}</p>
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import api from '../api'

const data = ref('')
const loading = ref(false)

const fetchData = async () => {
  loading.value = true
  try {
    const response = await api.get('/system/stats')
    data.value = response.data
  } catch (error) {
    console.error(error)
  } finally {
    loading.value = false
  }
}

onMounted(() => {
  fetchData()
})
</script>
```

---

## 🚀 Prochaines étapes

1. **Personnaliser les couleurs** - Modifier `frontend/tailwind.config.js`
2. **Ajouter des endpoints** - Créer de nouveaux fichiers dans `backend/app/api/endpoints/`
3. **Implémenter Https** - Ajouter un certificat SSL
4. **Déployer** - Voir [README.md](../README.md) section "Déploiement"

---

## 📖 Ressources

- [FastAPI Documentation](https://fastapi.tiangolo.com)
- [Vue 3 Guide](https://vuejs.org)
- [Tailwind CSS](https://tailwindcss.com)
- [Docker Python SDK](https://docker-py.readthedocs.io)
- [python-pam](https://github.com/firecat53/python-pam)

---

## 💡 Tips

- 🔄 L'API auto-recharge avec `--reload` en dev
- 🔍 Docs Swagger : http://localhost:8000/docs
- 📊 Dashboard rafraîchit tous les 5 secondes
- 🔐 Les tokens expirent après 8 heures
- 📱 L'interface est responsive (mobile/tablette)

---

Bienvenue dans InnotexBoard ! 🎉