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

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

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

2. Installer les dépendances

pip install -r requirements.txt

3. Configuration

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

Copy-Item env.example .env

Modifiez le fichier .env avec vos informations Nextcloud :

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

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

# 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

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

{
  "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 :

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

{
  "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 :

curl http://localhost:8000/info/Documents/rapport.pdf

5. Télécharger un fichier en Base64

GET /download-base64/{path}

Télécharge un fichier depuis Nextcloud et le retourne encodé en base64.

Paramètres :

• path : Chemin complet du fichier (ex: /Documents/rapport.pdf)

Exemples :

# Télécharger un fichier
curl http://localhost:8000/download-base64/Documents/rapport.pdf

# Avec PowerShell
$response = Invoke-RestMethod -Uri "http://localhost:8000/download-base64/Documents/rapport.pdf"
$fileBase64 = $response.file.file_base64
# Décoder le fichier
$bytes = [Convert]::FromBase64String($fileBase64)
[System.IO.File]::WriteAllBytes("C:\chemin\destination\rapport.pdf", $bytes)

Réponse exemple :

{
  "success": true,
  "file": {
    "name": "rapport.pdf",
    "path": "/Documents/rapport.pdf",
    "size": 1024567,
    "content_type": "application/pdf",
    "file_base64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBl..."
  }
}

6. 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 :

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

{
  "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
│   ├── download_base64.py  # Télécharger un fichier en base64
│   ├── upload.py       # Upload de fichiers
│   ├── upload_base64.py    # Upload de fichiers en base64
│   └── 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 :

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

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

📝 Licence

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