PyNextcloud/README.md

# PyNextcloud - API FastAPI pour Nextcloud

API REST construite avec FastAPI pour interagir avec un serveur Nextcloud et lister les fichiers et dossiers.

## 📋 Prérequis

- Python 3.8 ou supérieur
- Un serveur Nextcloud avec accès API
- Identifiants Nextcloud (username et password)

## 🚀 Installation

### 1. Créer un environnement virtuel

```powershell
# Créer l'environnement virtuel
python -m venv venv

# Activer l'environnement virtuel
.\venv\Scripts\Activate.ps1
```

### 2. Installer les dépendances

```powershell
pip install -r requirements.txt
```

### 3. Configuration

Créez un fichier `.env` à la racine du projet (vous pouvez copier `env.example`) :

```powershell
Copy-Item env.example .env
```

Modifiez le fichier `.env` avec vos informations Nextcloud :

```env
NEXTCLOUD_URL=https://votre-serveur-nextcloud.com
NEXTCLOUD_USERNAME=votre_username
NEXTCLOUD_PASSWORD=votre_password

APP_HOST=0.0.0.0
APP_PORT=8000
```

## 🎯 Utilisation

### Démarrer le serveur

```powershell
# Méthode 1 : Avec uvicorn directement
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Méthode 2 : Avec Python
python main.py
```

Le serveur démarre sur `http://localhost:8000`

### Documentation interactive

Une fois le serveur démarré, accédez à :
- Documentation Swagger UI : `http://localhost:8000/docs`
- Documentation ReDoc : `http://localhost:8000/redoc`

## 🐳 Déploiement avec Docker

### Avec Docker Compose (Local)

```powershell
# 1. Assurez-vous que le fichier .env est configuré
Copy-Item env.example .env
notepad .env

# 2. Modifier temporairement le docker-compose.yml pour exposer le port
# Ajoutez dans la section pynextcloud :
#   ports:
#     - "8000:8000"

# 3. Construire et lancer le conteneur
docker-compose up -d

# 4. Voir les logs
docker-compose logs -f

# 5. Arrêter le conteneur
docker-compose down
```

L'API sera accessible sur `http://localhost:8000`

**Note :** Le `docker-compose.yml` est optimisé pour Coolify (pas de port binding). Pour un usage local, ajoutez temporairement `ports: - "8000:8000"` dans la configuration.

### Déploiement sur Coolify 🚀

**Configuration Coolify :**

1. **Connectez votre repository Git** à Coolify

2. **Variables d'environnement à définir dans Coolify :**
   ```
   NEXTCLOUD_URL=https://votre-serveur-nextcloud.com
   NEXTCLOUD_USERNAME=votre_username
   NEXTCLOUD_PASSWORD=votre_password
   ```

3. **Coolify détectera automatiquement** le `Dockerfile` et le `docker-compose.yml`

4. **Port à exposer :** 8000 (port interne)

5. **Health check :** `/health` (déjà configuré dans le docker-compose.yml)

6. **⚠️ Important :** Ne configurez PAS de port externe dans Coolify. Le reverse proxy Traefik gère automatiquement le routage.

**Build automatique :**
- Coolify construira automatiquement l'image à chaque push sur la branche configurée
- Le conteneur redémarrera automatiquement en cas d'échec grâce au health check
- Accédez à l'API via le domaine configuré dans Coolify (ex: `https://pynextcloud.votre-domaine.com`)

### Construire l'image Docker manuellement

```powershell
# Construire l'image
docker build -t pynextcloud-api .

# Lancer le conteneur
docker run -d \
  -p 8000:8000 \
  --env-file .env \
  --name pynextcloud \
  pynextcloud-api

# Voir les logs
docker logs -f pynextcloud
```

## 📡 Endpoints disponibles

### 1. Route racine
```
GET /
```
Retourne un message d'accueil et le lien vers la documentation.

### 2. Health Check
```
GET /health
```
Vérifie l'état de l'API et la connexion à Nextcloud.

**Réponse exemple :**
```json
{
  "status": "healthy",
  "nextcloud_connected": true
}
```

### 3. Lister un répertoire
```
GET /list/{path}
```
Liste tous les fichiers et dossiers d'un répertoire Nextcloud.

**Paramètres :**
- `path` : Chemin du répertoire (utilisez `/` pour la racine)

**Exemples :**
```powershell
# Lister la racine
curl http://localhost:8000/list/

# Lister le dossier Documents
curl http://localhost:8000/list/Documents

# Lister un sous-dossier
curl http://localhost:8000/list/Documents/MonDossier
```

**Réponse exemple :**
```json
{
  "path": "/Documents",
  "total_items": 5,
  "summary": {
    "directories": 2,
    "files": 3
  },
  "items": [
    {
      "name": "rapport.pdf",
      "path": "/Documents/rapport.pdf",
      "is_dir": false,
      "size": 1024567,
      "content_type": "application/pdf",
      "last_modified": "2025-10-20T10:30:00",
      "etag": "abc123"
    },
    {
      "name": "Images",
      "path": "/Documents/Images",
      "is_dir": true,
      "size": 0,
      "content_type": null,
      "last_modified": "2025-10-19T15:20:00",
      "etag": "def456"
    }
  ]
}
```

### 4. Informations sur un fichier/dossier
```
GET /info/{path}
```
Obtient les informations détaillées d'un fichier ou dossier spécifique.

**Exemples :**
```powershell
curl http://localhost:8000/info/Documents/rapport.pdf
```

### 5. Upload un fichier
```
POST /upload
```
Upload un fichier vers un dossier Nextcloud.

**Paramètres (form-data) :**
- `file` : Le fichier à uploader **(requis)**
- `path` : Chemin du dossier de destination (ex: `/Documents`) **(requis)**
- `filename` : Nom du fichier (optionnel, utilise le nom original si non spécifié)

**Exemples :**
```powershell
# Upload simple
$file = Get-Item "C:\chemin\vers\monfichier.pdf"
$form = @{
    file = $file
    path = "/Documents"
}
Invoke-WebRequest -Uri "http://localhost:8000/upload" -Method POST -Form $form

# Upload avec renommage
$form = @{
    file = Get-Item "C:\chemin\vers\rapport.pdf"
    path = "/Documents/Projets"
    filename = "rapport_annuel_2025.pdf"
}
Invoke-WebRequest -Uri "http://localhost:8000/upload" -Method POST -Form $form
```

**Dans Postman :**
- Method: **POST**
- URL: `http://localhost:8000/upload`
- Body: **form-data**

| Key | Type | Value |
|-----|------|-------|
| file | File | *[Sélectionnez votre fichier]* |
| path | Text | /Documents |
| filename | Text | mon_fichier.pdf *(optionnel)* |

**Réponse exemple :**
```json
{
  "success": true,
  "message": "Fichier uploadé avec succès",
  "file": {
    "name": "rapport_annuel_2025.pdf",
    "path": "/Documents/Projets/rapport_annuel_2025.pdf",
    "size": 1024567,
    "content_type": "application/pdf"
  }
}
```

## 🔧 Structure du projet

```
PyNextcloud/
│
├── main.py              # Application FastAPI avec auto-chargement des contrôleurs
├── config.py            # Configuration de l'application
├── utils.py             # Fonctions utilitaires
├── controllers/         # 📁 Dossier des contrôleurs (auto-chargés)
│   ├── __init__.py
│   ├── root.py         # Route racine
│   ├── health.py       # Health check
│   ├── list.py         # Lister les fichiers/dossiers
│   ├── info.py         # Informations d'un fichier/dossier
│   ├── upload.py       # Upload de fichiers
│   └── debug.py        # Routes de débogage
├── requirements.txt     # Dépendances Python
├── env.example         # Exemple de fichier de configuration
├── .env                # Configuration (à créer, non versionné)
├── Dockerfile          # 🐳 Image Docker
├── docker-compose.yml  # 🐳 Configuration Docker Compose
├── .dockerignore       # Fichiers à ignorer pour Docker
├── .gitignore          # Fichiers à ignorer pour Git
└── README.md           # Ce fichier
```

### 🎯 Architecture modulaire avec auto-chargement

Le projet utilise une architecture modulaire où tous les contrôleurs dans le dossier `controllers/` sont **automatiquement chargés** au démarrage.

**Pour ajouter un nouveau endpoint :**
1. Créez un nouveau fichier dans `controllers/`, par exemple `controllers/mon_endpoint.py`
2. Créez un `router` FastAPI dans ce fichier
3. C'est tout ! Le contrôleur sera automatiquement chargé au démarrage

**Exemple de nouveau contrôleur :**
```python
# controllers/mon_endpoint.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/mon-endpoint")
async def mon_endpoint():
    return {"message": "Mon nouveau endpoint"}
```

## 🛠️ Dépendances principales

- **FastAPI** : Framework web moderne et rapide
- **Uvicorn** : Serveur ASGI
- **nc-py-api** : Client Python pour l'API Nextcloud
- **python-dotenv** : Gestion des variables d'environnement
- **pydantic** : Validation des données

## ⚠️ Notes importantes

1. **Sécurité** : Ne committez jamais votre fichier `.env` dans Git. Il contient vos identifiants.
2. **Chemins** : Les chemins doivent être relatifs à la racine de votre espace Nextcloud.
3. **Authentification** : L'API utilise l'authentification basique avec username/password.

## 🐛 Dépannage

### Erreur de connexion à Nextcloud
- Vérifiez que l'URL de votre serveur Nextcloud est correcte
- Vérifiez vos identifiants
- Assurez-vous que votre serveur Nextcloud est accessible

### Erreur 404 sur un répertoire
- Vérifiez que le chemin existe dans votre Nextcloud
- Les chemins sont sensibles à la casse

### Problèmes d'activation de l'environnement virtuel
Si vous avez une erreur de sécurité PowerShell, exécutez :
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

## 📝 Licence

Ce projet est libre d'utilisation pour vos besoins personnels et professionnels.