Initial commit
This commit is contained in:
innotex
283
QUICKSTART.md
Normal file
283
QUICKSTART.md
Normal file
@@ -0,0 +1,283 @@
|
||||
# 📖 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 ! 🎉
|
||||
Reference in New Issue
Block a user