Nextcloud Collective to Matrix Bot 🤖

Bot Docker per estrarre automaticamente pagine da Nextcloud Collective e inviarle su Matrix.

📋 Setup

1. Struttura file

nextcloud-matrix-bot/
├── bot.py
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env
└── logs/

2. Configurazione Nextcloud

Crea utente bot con sola lettura (CONSIGLIATO):

1. In Nextcloud: Crea nuovo utente bot-matrix-reader
2. Vai alla cartella Collective da condividere
3. Click destro → Condivisione → Aggiungi utente bot-matrix-reader
4. Deseleziona "Può modificare" per garantire sola lettura
5. Login come bot-matrix-reader e genera App Password

Oppure usa App Password utente esistente:

1. Vai su Nextcloud → Impostazioni → Sicurezza
2. Sotto "Dispositivi e sessioni" crea una nuova App Password
3. Copia il token generato (formato: xxxxx-xxxxx-xxxxx-xxxxx-xxxxx)
4. ⚠️ Nota: eredita tutti i permessi dell'utente

Trova il path del Collective:

• Solitamente: Collectives/NomeDelTuoCollective
• Verifica navigando via WebDAV: https://tuo-nextcloud.com/remote.php/dav/files/tuo-user/

3. Configurazione Matrix

Ottieni Access Token:

curl -XPOST 'https://matrix.org/_matrix/client/v3/login' \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "tuo-bot-user",
    "password": "tua-password"
  }'

Trova Room ID:

• In Element: Impostazioni stanza → Avanzate → ID stanza interno
• Formato: !AbCdEfGhIjKlMnOpQr:matrix.org

4. File .env

Copia .env.example in .env e compila:

cp .env.example .env
nano .env

🚀 Utilizzo

Esecuzione singola

# Build immagine
docker-compose build

# Esegui una volta
docker-compose run --rm nextcloud-matrix-bot

Esecuzione schedulata con cron host (CONSIGLIATO)

Il bot si chiude automaticamente dopo l'esecuzione, perfetto per cron:

# Apri crontab
crontab -e

# Esegui ogni giorno alle 9:00
0 9 * * * cd /path/to/nextcloud-matrix-bot && /usr/bin/docker-compose run --rm nextcloud-matrix-bot >> /path/to/logs/cron.log 2>&1

# Esegui ogni ora
0 * * * * cd /path/to/nextcloud-matrix-bot && /usr/bin/docker-compose run --rm nextcloud-matrix-bot

# Esegui ogni 6 ore
0 */6 * * * cd /path/to/nextcloud-matrix-bot && /usr/bin/docker-compose run --rm nextcloud-matrix-bot

Tip per testare il cron:

# Test manuale che simula il cron
cd /path/to/nextcloud-matrix-bot && docker-compose run --rm nextcloud-matrix-bot

# Verifica path Docker nel cron
which docker-compose
# Usa il path completo nel crontab (es: /usr/local/bin/docker-compose)

Esecuzione continua con restart policy

# Modifica docker-compose.yml per usare cron interno
# Poi avvia il servizio
docker-compose up -d

🔧 Opzioni configurabili

Variabile	Default	Descrizione
DAYS_BACK	1	Giorni indietro da controllare
COLLECTIVE_PATH	Collectives/MyCollective	Path alla cartella Collective
RECURSIVE	true	Analizza sottocartelle ricorsivamente
TZ	Europe/Rome	Timezone per log

📝 Log

I log vengono salvati in logs/ e mostrano:

• ✅ File inviati con successo
• ❌ Errori di connessione o invio
• 📊 Statistiche esecuzione

🐛 Troubleshooting

Errore 401 Nextcloud:

• Verifica App Password (non la password normale)
• Controlla username corretto

Errore 403 Matrix:

• Verifica Access Token valido
• Controlla che il bot sia nella room

Nessun file trovato:

• Verifica COLLECTIVE_PATH corretto
• Controlla che ci siano file .md modificati nel periodo

Errore WebDAV:

# Test connessione manuale
curl -u "username:app-password" \
  "https://tuo-nextcloud.com/remote.php/dav/files/username/Collectives/"

🔐 Sicurezza

• ✅ Usa App Password, non password principale
• ✅ File .env in .gitignore
• ✅ Access Token Matrix dedicato per il bot
• ✅ Permessi minimi necessari

📦 Aggiornamenti

# Pull ultime modifiche
git pull

# Rebuild container
docker-compose build --no-cache

# Restart servizio
docker-compose restart