Vai al contenuto

OnlyOffice + FastAPI microservizio

Questo documento raccoglie i passaggi 1→4 richiesti nella sequenza: (1) ambiente, (2) avvio, (3) template SafeOps/iframe, (4) verifica callback/Minio.

1. Preparare le variabili d’ambiente

  1. Copia onlyoffice_service/.env.example in onlyoffice_service/.env ed imposta i valori reali:
  2. ONLYOFFICE_URL=http://onlyoffice
  3. ONLYOFFICE_SECRET (deve essere uguale a quello configurato in OnlyOffice e nell’URL del documento).
  4. MINIO_* secondo la macchina che ospita MinIO; per un MinIO già attivo sul nodo 10.50.0.200 basta settare: 
    MINIO_ENDPOINT=10.50.0.200:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=Zaq12wsx-234
MINIO_BUCKET=safeops
MINIO_SECURE=true
  5. JWT_EXP_SECONDS può restare 300.
  6. Il microservizio legge prima .env all’interno di onlyoffice_service/, quindi eventuali .env esterni vengono comunque considerati come fallback.
  7. Se il portale gira in HTTPS, non usare localhost per il browser. Pubblica OnlyOffice via reverse proxy e imposta nel .env principale: 
    ONLYOFFICE_SERVICE_URL=http://127.0.0.1:8000
ONLYOFFICE_DOCSERVER_URL=https://besant.nxt-sense.eu/onlyoffice-docs
ONLYOFFICE_CALLBACK_URL=https://besant.nxt-sense.eu/onlyoffice-service/v1/editor/callback
    Il template nginx di riferimento è deploy/nginx/safeops.conf.example e include già i path /onlyoffice-docs/ e /onlyoffice-service/.

2. Avviare i container (FastAPI, OnlyOffice, Minio)

  1. docker-compose -f docker-compose.onlyoffice.yml up --build
  2. I servizi esposti siano raggiungibili in locale su:
  3. http://localhost:9000 for MinIO (console :9001).
  4. http://localhost:9082 for OnlyOffice Document Server.

  5. http://localhost:8000/v1/editor/open for il microservizio FastAPI.

  6. Se servono i bucket, crea safeops con mc:

docker exec safeops-minio mc alias set local http://localhost:9000 minioadmin minioadminpassword
docker exec safeops-minio mc mb --ignore-existing local/safeops

Se MinIO è già collegato a SafeOps, i file migrati riusciranno a essere recuperati durante open.

3. Template SafeOps / iframe

3.1. Chiamata open

Vai a open con un payload JSON (l’esempio usa fetch sul microservizio FastAPI):

const openPayload = {
  document_id: 123,
  file_key: "documenti/verbali/verbale.docx",
  file_name: "Verbale.docx",
  file_type: "docx",
  bucket: "safeops",
  callback_url: "http://localhost:8000/v1/editor/callback",
  permissions: 4
};

const response = await fetch("http://localhost:8000/v1/editor/open", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(openPayload)
});
const editorPayload = await response.json();

3.2. Embed DocEditor

Nel template SafeOps puoi inserire:

<script src="http://localhost:9082/web-apps/apps/api/documents/api.js"></script>
<div id="onlyoffice-editor" style="height:100vh;width:100%"></div>
<script>
  async function openOnlyOffice() {
    const resp = await fetch("/api/proxy-to-onlyoffice-open", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ document_id: 123, file_key: "...", ... })
    });
    const { document, editorConfig, onlyofficeUrl, jwt } = await resp.json();
    new window.DocEditor("onlyoffice-editor", {
      width: "100%",
      height: "100%",
      document,
      documentType: document.fileType,
      token: jwt,
      editorConfig: {
        ...editorConfig,
        callbackUrl: editorConfig.callbackUrl
      },
      key: document.key,
    });
  }
  openOnlyOffice();
</script>

Nota: window.DocEditor è fornito dal file api.js del Document Server. L’oggetto document contiene il key serializzato (bucket+object) che you can store to call /v1/editor/callback if needed.

4. Verifica/callback/Minio

  1. When OnlyOffice calls callbackUrl, the FastAPI microservice checks status and writes back to MinIO. Puoi controllare i log di safeops-onlyoffice-service per confermare che il PUT su MinIO (bucket + key) vada a buon fine.
  2. Per controllare manualmente che MinIO contenga l’oggetto aggiornato:
docker exec safeops-minio mc cp local/safeops/documenti/verbali/verbale.docx /tmp/verbale.docx
docker exec safeops-minio ls local/safeops/documenti/verbali/

  1. Se l’URL di callback deve essere pubblico, esponi http://localhost:8000/v1/editor/callback via reverse proxy (nginx, Traefik) oppure usa un tunnel (es. ngrok).

  2. Per testare il flusso end-to-end:

  3. Apri l’editor nel frontend e modifica un documento.
  4. Attendi che OnlyOffice chiami /v1/editor/callback con status 2 o 6.
  5. Controlla in MinIO che il file aggiornato sia presente tramite mc.

Questo schema può essere esteso a più servizi SafeOps/gestionali: basta chiamare la stessa API /v1/editor/open e usare il medesimo callback per ricevere il file ritornato da OnlyOffice.

Helper backend per SafeOps

Se preferisci evitare chiamate dirette a /v1/editor/open dal browser, puoi utilizzare l’helper Python in app/helpers/onlyoffice.py.

  1. Importa open_document e passa i metadati:
from app.helpers.onlyoffice import open_document

payload = open_document(
    document_id=123,
    file_key="documenti/verbali/verbale.docx",
    file_name="Verbale.docx",
    file_type="docx",
    callback_url="http://localhost:8000/v1/editor/callback",
)
  1. open_document ritorna il JSON completo (document, editorConfig, jwt). Puoi restituirlo da un endpoint protetto del tuo backend e lasciare al browser il solo compito di istanziare DocEditor.
  2. L’helper legge ONLYOFFICE_SERVICE_URL dalla variabile d’ambiente (impostata in .env) e solleva OnlyOfficeHelperError in caso di fallimento.

View pronta all’uso

Se vuoi bypassare del tutto l’iframe manuale, puoi chiamare la nuova view protetta che fa tutto lo stesso lavoro:

GET /onlyoffice/editor?document_id=123&file_key=documenti/verbali/verbale.docx

La view:

  • chiama open_document passando document_id, file_key, file_name (derivata dal path se manca) e callback_url (legge ONLYOFFICE_CALLBACK_URL).
  • monta DocEditor usando il template onlyoffice/editor.html e importa api.js dal Document Server (URL soggetto a ONLYOFFICE_DOCSERVER_URL).
  • richiede che l’utente sia autenticato (login_required), quindi può essere inserita in una scheda sicura di SafeOps.

Puoi includere questa view nel menu SafeOps registrando una voce personalizzata o incapsularla in un’iframe all’interno di un portale esistente.

Creazione guidata documento

La view /onlyoffice/create permette di creare un stub DOCX, salvarlo in MinIO e aprirlo subito nell’editor. Basta:

  1. Accedere alla voce “Crea documento” nel menu Documenti (richiede login).
  2. Compilare titolo e formato (al momento supportiamo solo DOCX).
  3. Submit genera il file tramite upload_bytes (payload docx vuoto), registra il metadata su stored_files e reindirizza l’utente su /onlyoffice/editor.

Questo è utile per partire da un documento nuovo senza dover caricare template manualmente.

Sincronizzazione menu per tenant

Se alcuni tenant (es. besant, safecondo) usano policy menu custom e non vedono ancora le voci, esegui lo script tools/onlyoffice_menu_sync.py:

python tools/onlyoffice_menu_sync.py --tenants besant safecondo

In alternativa (dopo aver installato dipendenze e caricato l’app) puoi usare il comando Flask:

FLASK_APP=app flask sync_onlyoffice_menu --tenants besant safecondo

Il tool inserisce o abilita in tabella menu_policy le record OnlyOffice Editor / Crea documento per ciascun tenant indicato. Puoi aggiungere altri tenant passandoli con --tenants.