RA4 — Teoria 2: FileBrowser, Microserveis i Gotenberg

Sessió: Dia 2 (refresc + pràctica 2)
Durada: ~20 minuts de teoria abans de la pràctica

1. Refresc ràpid del dia anterior

Nextcloud en 3 línies

Nextcloud = plataforma de col·laboració self-hosted (fitxers + més)
Es desplega amb docker compose: servei app (Apache+PHP) + servei db (MariaDB)
Gestió d'usuaris: interfície web o occ (CLI). occ és el camí per automatitzar.

Comandes clau que heu de recordar

# Engegar/Aturar
docker compose up -d
docker compose down

# Logs
docker compose logs -f app

# occ (CLI de Nextcloud)
docker compose exec -u www-data app php occ <comanda>

# Crear usuari via occ
OC_PASS="pass" docker compose exec -u www-data -e OC_PASS app \
  php occ user:add --password-from-env --display-name "Nom" --group "Grup" usuari

2. FileBrowser: gestor de fitxers web lleuger

2.1 Què és i per a què serveix

FileBrowser és un gestor de fitxers web autònom (no necessita cap altre servei extern). Permet:

Navegar, pujar, descarregar i gestionar fitxers via navegador
Gestió d'usuaris amb permisos per ruta
Previsualització de fitxers (imatges, PDF, vídeo)
Compartició d'arxius via enllaç

A diferència de Nextcloud, FileBrowser és molt lleuger (~20 MB) i no té bases de dades ni instal·lació complexa. Ideal per a:

Repositoris de fitxers d'equip senzills
Accés HTTP a un directori del servidor
Entorns amb pocs recursos

2.2 Arquitectura i API REST

FileBrowser exposa una API REST que permet:

Autenticació i obtenció d'un token JWT
Llistar fitxers i directoris
Pujar i descarregar fitxers
Gestionar usuaris (amb compte d'admin)

Flux d'autenticació JWT:

Client                         FileBrowser
  |                                 |
  |-- POST /api/login               |
  |   {"username":"...","password":"..."}
  |                                 |
  |<-- {"token": "eyJ..."}          |
  |                                 |
  |-- GET /api/resources/           |
  |   Authorization: Bearer eyJ... |
  |                                 |
  |<-- [{nom: "fitxer1.txt",...}]   |

El token JWT té una caducitat (per defecte 2 hores). En scripts s'obté el token al principi i es reutilitza per a totes les operacions.

2.3 Usuaris i permisos a FileBrowser

Cada usuari de FileBrowser té:

Directori arrel (scope): la ruta a la qual té accés. No pot sortir d'aquesta ruta.
Permisos: pot crear, editar, renombrar, descarregar, compartir, administrar

L'usuari admin pot gestionar altres usuaris i té accés a tot.

3. Microserveis: concepte i aplicació

3.1 Arquitectura de microserveis

Un microservei és un servei petit, amb una responsabilitat concreta, que exposa una API (generalment HTTP/REST) i pot ser invocat per altres serveis o aplicacions.

[Aplicació principal PHP]
        |
        | HTTP POST (fitxer .docx)
        ▼
[Microservei Gotenberg]  ←── contenidor Docker independent
        |
        | retorna PDF
        ▼
[Aplicació principal PHP]
        |
        | desa el PDF
        ▼
    [disc / Nextcloud]

Avantatges dels microserveis:

Cada servei es pot escalar, actualitzar o substituir de forma independent
Separació de responsabilitats: l'aplicació principal no necessita saber com es fa la conversió
Reutilitzable per diverses aplicacions del mateix servidor

Inconvenient principal:

Afegeix latència de xarxa entre serveis
Més components a gestionar i monitorar

3.2 Comunicació entre serveis en Docker Compose

En un compose.yaml, els serveis de la mateixa xarxa es parlen per nom de servei:

services:
  app:       # PHP/web
    networks: [interna]

  gotenberg:
    networks: [interna]
    # app accedeix a gotenberg via http://gotenberg:3000

networks:
  interna:

Des del contenidor app, la URL de Gotenberg és http://gotenberg:3000 (no localhost:3000).

Error típic dels alumnes: intentar usar localhost:3000 des d'un contenidor per accedir a un altre. localhost dins un contenidor es refereix al propi contenidor, no a l'amfitrió.

4. Gotenberg: API de conversió a PDF

4.1 Què és Gotenberg

Gotenberg és una API REST containeritzada que converteix documents a PDF. Usa internament:

Chromium: per convertir HTML, Markdown i URLs a PDF
LibreOffice: per convertir documents Office (.docx, .xlsx, .pptx, .odt...) a PDF

Des del punt de vista del client: envieu un fitxer per HTTP, rebeu un PDF. No cal instal·lar LibreOffice ni Chromium al vostre servidor principal.

4.2 Endpoints principals

Endpoint	Entrada	Sortida
`POST /forms/chromium/convert/url`	URL web	PDF
`POST /forms/chromium/convert/html`	fitxer HTML	PDF
`POST /forms/libreoffice/convert`	.docx/.xlsx/.odt/...	PDF
`POST /forms/pdfengines/merge`	múltiples PDFs	PDF combinat

Totes les peticions usen multipart/form-data.

4.3 Exemples de crides

Convertir una URL a PDF (Bash + curl):

curl -s -X POST http://localhost:3000/forms/chromium/convert/url \
  -F "url=https://example.com" \
  -o resultat.pdf

Convertir un fitxer DOCX a PDF:

curl -s -X POST http://localhost:3000/forms/libreoffice/convert \
  -F "files=@document.docx" \
  -o document.pdf

Des de PHP (usant cURL):

$ch = curl_init('http://gotenberg:3000/forms/libreoffice/convert');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'files' => new CURLFile('/ruta/al/fitxer.docx')
]);
$pdf = curl_exec($ch);
file_put_contents('resultat.pdf', $pdf);

4.4 Seguretat: Gotenberg no té autenticació

Per defecte, Gotenberg no té cap mecanisme d'autenticació. Qualsevol que pugui accedir al port 3000 pot fer conversions il·limitades (costoses en CPU).

Per tant, en producció:

Mai exposar el port de Gotenberg directament a Internet
Mantenir-lo en una xarxa interna Docker, accessible només des dels serveis que el necessiten
Si cal accés extern: posar un proxy invers amb autenticació al davant

En la nostra pràctica, el port 3000 de Gotenberg sí que l'exposem a l'amfitrió perquè fem proves directes des de la terminal. En un desplegament real, es llevaría la secció ports i s'accediria via xarxa interna Docker.

5. El `compose.yaml` final: tres serveis integrats

Al final de la Pràctica 2 tindreu un compose.yaml que aixeca tres serveis junts:

┌──────────────────────────────────────────────────────────┐
│                    amfitrió (Debian 13)                   │
│                                                          │
│  port 8080 ──► [nextcloud] ─┐                            │
│  port 8181 ──► [filebrowser]│  xarxa interna             │
│  port 3000 ──► [gotenberg]  │  (nc_net)                  │
│                             │                            │
│                        [mariadb] (sense port extern)     │
└──────────────────────────────────────────────────────────┘

La clau pedagògica: cada servei té la seva responsabilitat, però es poden combinar per crear fluxos de treball (pujar un DOCX a FileBrowser → convertir-lo a PDF via Gotenberg → desar el PDF).

6. Resum dels criteris coberts avui

Criteri	Com es treballa a la Pràctica 2
4.3 Instal·lació	Desplegar FileBrowser i Gotenberg amb Docker Compose
4.4 Configuració en intranet	Xarxa interna, ports i seguretat de Gotenberg
4.5 Gestió de comptes	Creació d'usuaris a FileBrowser via web i API REST
4.6 Criteris de seguretat	Permisos per ruta a FileBrowser, Gotenberg sense accés extern
4.8 Documentació	`docker-compose.yaml` final comentat + breu manual

Documentació oficial:

FileBrowser: filebrowser.org/api
Gotenberg: gotenberg.dev/docs