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

# 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 :

curl http://localhost:8000/health

Frontend

# 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)

# 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 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

# 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)

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

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

"Permission denied" (Docker)

# 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)

# 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"

# 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 :

<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 section "Déploiement"

---

📖 Ressources

• FastAPI Documentation
• Vue 3 Guide
• Tailwind CSS
• Docker Python SDK
• 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 ! 🎉