¿Tienes una biblioteca repleta de películas, series, documentales o música y quieres acceder a ella desde cualquier televisor, smartphone o consola de tu casa? Crear tu propio servidor multimedia personal es la mejor decisión que puedes tomar.

Cuando pensamos en servidores domésticos, solemos imaginar distribuciones tradicionales como Ubuntu Server o Debian. Sin embargo, CachyOS —la distribución ultrarrápida basada en Arch Linux y optimizada para procesadores modernos— es una opción formidable para este propósito. Gracias a sus optimizaciones de kernel y su gestión de rendimiento en tiempo real, tu servidor multimedia volará. ⚡

En esta guía práctica y directa al grano, aprenderás cómo instalar, configurar y sacarle el máximo provecho a Plex Media Server en CachyOS, paso a paso y sin complicaciones. ¡Manos a la obra! 🛠️

1. ¿Por qué elegir CachyOS para tu servidor Plex? 🏎️

Antes de entrar en comandos de terminal, vale la pena entender qué ventajas aporta CachyOS a un entorno multimedia:

1. Rendimiento compilado para tu procesador: CachyOS aprovecha las instrucciones avanzadas (x86-64-v3 y v4), lo que reduce el uso innecesario de ciclos de CPU.
2. Kernels optimizados (BORE / EEVDF): Gestionan de forma sobresaliente los procesos en segundo plano. Mientras Plex escanea metadatos o convierte un video, el resto del sistema no sufre tirones.
3. Drivers gráficos al día: Al estar basada en Arch Linux con modelo rolling release, cuentas siempre con las versiones más recientes de Mesa, VA-API y controladores de video para transcodificación por hardware.

2. Requisitos previos y puesta a punto del sistema 💻

Para comenzar con buen pie, es importante que tu instalación de CachyOS esté completamente actualizada y cuente con las herramientas esenciales de desarrollo y compilación.

Abre tu emulador de terminal favorito y ejecuta:

Bash

# 1. Actualizar repositorios y paquetes del sistema
sudo pacman -Syu

# 2. Instalar herramientas de compilación básicas
sudo pacman -S --needed base-devel git

Verifica también que cuentas con un asistente para AUR (Arch User Repository) como paru o yay.

3. Método 1: Instalación Nativa vía AUR (Recomendado) 📦

La instalación nativa es la opción más directa y ligera, ya que integra Plex como un servicio nativo del sistema operativo gestionado por systemd.

Paso 1: Descargar e instalar el paquete

Ejecuta el siguiente comando con tu gestor AUR:

Bash

paru -S plex-media-server

(Si utilizas yay, simplemente sustituye paru por yay).

El asistente compilará e integrará los binarios oficiales de Plex en el sistema.

Paso 2: Habilitar e iniciar el servicio

Una vez terminada la instalación, debemos indicarle al sistema que arranque Plex inmediatamente y que lo inicie de forma automática cada vez que enciendas el equipo:

Bash

sudo systemctl enable --now plexmediaserver.service

Paso 3: Comprobar el estado

Para asegurarte de que el servicio está funcionando sin errores, ejecuta:

Bash

systemctl status plexmediaserver.service

Si todo ha ido bien, verás un punto verde indicando que el estado es active (running). ✅

4. Método 2: Despliegue mediante Docker y Docker Compose 🐳

Si prefieres aislar Plex del sistema base o planeas combinarlo con otras aplicaciones (como gestores de descargas o paneles de control), Docker es una alternativa modular y muy ordenada.

Paso 1: Instalar el motor Docker

Bash

sudo pacman -S docker docker-compose
sudo systemctl enable --now docker.service
sudo usermod -aG docker $USER

(Nota: Cierra y vuelve a abrir tu sesión de usuario para que el grupo Docker tome efecto).

Paso 2: Crear el archivo docker-compose.yml

Crea una carpeta para el proyecto y dentro genera el archivo de configuración:

Bash

mkdir -p ~/servidor-plex && cd ~/servidor-plex
nano docker-compose.yml

Pega la siguiente configuración (usando la imagen oficial de LinuxServer):

YAML

services:
  plex:
    image: lscr.io/linuxserver/plex:latest
    container_name: plex
    network_mode: host
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/Mazatlan
      - VERSION=docker
    volumes:
      - ./config:/config
      - /mnt/almacenamiento/series:/tv
      - /mnt/almacenamiento/peliculas:/movies
    restart: unless-stopped

Paso 3: Levantar el contenedor

Para ponerlo en marcha en segundo plano:

Bash

docker compose up -d

5. El Gran Dolor de Cabeza en Linux: Permisos y Discos Secundarios 🔑

El 90% de los problemas en Plex bajo Linux ocurren cuando el servidor no puede ver las películas que tienes guardadas en tus discos.

En la instalación nativa, el servidor se ejecuta bajo el usuario del sistema plex. Este usuario necesita permisos de lectura y ejecución en las carpetas donde guardas tu contenido.

Regla de oro: No guardes medios dentro de tu /home

Evita colocar tus carpetas de películas dentro de /home/tu_usuario/. En Arch Linux y CachyOS, los directorios personales tienen permisos estrictos (700 o 750) que bloquean el acceso a cualquier servicio externo.

👉 Lo ideal es utilizar un punto de montaje en la raíz, como /mnt/almacenamiento o /media/multimedia.

Asignar permisos correctos (Formato Linux: ext4 / btrfs)

Si tus discos tienen formato de Linux, ejecuta estos comandos para garantizar lectura:

Bash

# Permisos 755 a todas las carpetas (para poder entrar y leerlas)
sudo find /mnt/almacenamiento -type d -exec chmod 755 {} +

# Permisos 644 a todos los archivos multimedia
sudo find /mnt/almacenamiento -type f -exec chmod 644 {} +

Montaje automático en /etc/fstab 📌

Para que tus discos duros secundarios o externos no desaparezcan al reiniciar el equipo, agrégalos a tu archivo de montajes permanente.

1. Identifica el UUID de tu disco:

Bash

lsblk -f

2. Abre el archivo de configuración:

Bash

sudo nano /etc/fstab

3. Añade la línea correspondiente al final del archivo:

• Para discos en formato ext4:

Plaintext

UUID=tu-uuid-aqui   /mnt/almacenamiento   ext4   defaults,noatime   0   2

• Para discos en formato NTFS (discos que usabas en Windows):

Plaintext

UUID=tu-uuid-aqui   /mnt/almacenamiento   ntfs-3g   uid=plex,gid=plex,dmask=022,fmask=133,windows_names   0   0

Guarda los cambios con Ctrl + O y sal con Ctrl + X.

6. Primer Acceso y Reclamar el Servidor 🌐

¡Es momento de entrar a la interfaz web y vincular tu cuenta de Plex!

1. Abre tu navegador web e ingresa a la siguiente dirección:Plaintexthttp://localhost:32400/web
2. Inicia sesión con tu cuenta de Plex (o regístrate gratis si aún no tienes una).
3. Sigue el asistente de bienvenida: asígnale un nombre a tu servidor (ejemplo: Servidor-CachyOS) y marca la casilla para permitir el acceso a tus medios fuera del hogar si lo requieres.
4. Añade tus bibliotecas: Selecciona si vas a añadir Películas, Series o Música y navega hasta la ruta de tus carpetas (ej. /mnt/almacenamiento/peliculas).

7. Optimización y Transcodificación por Hardware ⚙️

La transcodificación ocurre cuando el dispositivo donde reproduces el video no soporta el formato nativo del archivo (por ejemplo, reproducir un archivo 4K HEVC en un navegador web antiguo).

Si tienes una suscripción activa a Plex Pass, puedes transferir esta carga pesada del procesador a tu tarjeta gráfica integrada o dedicada:

Para asegurarte de que el usuario plex puede interactuar directamente con la GPU en una instalación nativa, agrégalo al grupo de video y render:

Bash

sudo usermod -aG video,render plex
sudo systemctl restart plexmediaserver.service

8. Configuración del Firewall y Acceso Remoto 🛡️

Si tienes activado un cortafuegos local (como ufw o firewalld), asegúrate de habilitar los puertos clave de Plex para que tus smart TVs y dispositivos móviles en la red local puedan comunicarse sin bloqueos:

Bash

# Si usas UFW:
sudo ufw allow 32400/tcp comment 'Plex Web & Media'
sudo ufw allow 1900/udp comment 'Plex DLNA'
sudo ufw allow 5353/udp comment 'Plex Discovery'
sudo ufw reload

9. Preguntas Frecuentes (FAQ) ❓

¿Plex es completamente gratuito?

Sí. Puedes ver todo tu contenido en red local, organizar bibliotecas con carátulas automáticas y reproducir en Smart TVs de forma 100% gratuita. Funciones avanzadas como la transcodificación por hardware o las descargas sin conexión requieren la suscripción opcional Plex Pass.

¿Cómo actualizo Plex en CachyOS?

Si instalaste mediante el método nativo (AUR), se actualizará automáticamente cada vez que actualices el sistema con paru -Syu o yay -Syu. Si usas Docker, basta con ejecutar docker compose pull y luego docker compose up -d.

¿Puedo acceder a mis películas desde fuera de mi casa?

Sí. En la sección Ajustes > Acceso Remoto de Plex puedes habilitar esta opción. Si tu router cuenta con UPnP funcionará automáticamente; de lo contrario, solo necesitas abrir y redirigir el puerto 32400 en el panel de control de tu router hacia la IP local de tu servidor.

Conclusión 🏁

Montar tu servidor Plex en CachyOS combina lo mejor de dos mundos: la inmensa versatilidad del ecosistema Arch Linux y la potencia de un kernel optimizado al milímetro para exprimir cada ciclo de tu hardware.

Siguiendo esta guía ya cuentas con un centro multimedia sólido, rápido y accesible desde cualquier rincón de tu hogar. ¡Prepara las palomitas y a disfrutar de tus contenidos favoritos! 🍿🎉

Si estás integrando SAP Business One Service Layer con una aplicación propia en PHP o CodeIgniter 4 para gestionar empleados y sus roles, es muy probable que en algún momento te topes con este comportamiento extraño: haces un PATCH a EmployeesInfo quitando un rol del arreglo EmployeeRolesInfoLines, Service Layer te responde 204 (éxito), pero al consultar de nuevo el empleado… el rol sigue ahí.

No es un bug de tu código. Es un comportamiento documentado (pero poco conocido) de cómo Service Layer maneja las colecciones hijas en las peticiones PATCH. En este post te explico la causa exacta y la solución con un ejemplo completo en PHP.

El síntoma

Un flujo típico para quitar un rol asignado a un empleado se ve así:

1. Haces GET a EmployeesInfo(empID) y traes la colección EmployeeRolesInfoLines.
2. Filtras en tu código el rol que quieres eliminar.
3. Mandas un PATCH de vuelta con el arreglo ya sin ese rol.
4. Service Layer responde HTTP 204 No Content — es decir, “todo salió bien”.
5. Vuelves a consultar el empleado… y el rol que “eliminaste” sigue en la lista.

El código no marca ningún error. El log de tu aplicación dice que la operación fue exitosa. Y sin embargo, en SAP no pasó nada.

La causa real: cómo funciona PATCH en Service Layer

Aquí está la clave que casi nadie documenta claramente: PATCH en SAP Business One Service Layer nunca elimina elementos de una colección hija por el simple hecho de omitirlos del arreglo.

Por definición, PATCH es una actualización parcial: aplica los cambios que le mandas y conserva silenciosamente todo lo que no esté presente en el payload. Si en tu arreglo EmployeeRolesInfoLines ya no incluyes el rol que querías borrar, Service Layer no lo interpreta como “bórralo” — simplemente lo ignora y lo deja como estaba.

Este mismo comportamiento se ha reportado en la comunidad de desarrolladores de SAP al trabajar con líneas de documentos (DocumentLines en órdenes de venta), y aplica exactamente igual a cualquier colección hija expuesta por Service Layer, incluyendo los roles de un empleado.

La solución: el header B1S-ReplaceCollectionsOnPatch

Service Layer sí tiene una forma de decirle “trata este arreglo como el reemplazo completo de la colección, no como una actualización parcial”: el header HTTP B1S-ReplaceCollectionsOnPatch: true.

Al incluir este header en tu petición PATCH, cualquier elemento que no esté presente en el arreglo que envías sí se elimina de la colección hija en SAP. Es exactamente el comportamiento que necesitas para dar de baja un rol.

⚠️ Importante antes de usarlo

Este header cambia el comportamiento para todas las colecciones hijas incluidas en ese PATCH, no solo la que te interesa. Si tu payload incluyera más de una colección hija, cualquiera que no mandes completa corre el riesgo de perder elementos. La recomendación es:

• Usarlo únicamente en los endpoints donde manipulas directamente EmployeeRolesInfoLines (agregar/quitar roles).
• No incluirlo en el PATCH general de datos del empleado (nombre, departamento, estatus), donde no estás tocando colecciones hijas.

Ejemplo completo en PHP (CodeIgniter 4)

Así queda la función completa para eliminar un rol de un empleado, con el flujo GET → filtrar → PATCH con el header correcto:

php

public function removeEmployeeRole($empID, $roleID) {
    helper('auth');
    $userName = user()->username;
    $empID = (int) $empID;
    $roleID = (int) $roleID;

    if ($empID <= 0 || $roleID <= 0) {
        return $this->respond(['status' => 400, 'message' => 'Faltan datos'], 400);
    }

    $dataSL = $this->serviceLayerModel->first();
    if (empty($dataSL)) {
        return $this->respond(['status' => 500, 'message' => 'No hay configuración Service Layer'], 500);
    }

    try {
        $conexionSap = $this->serviceLayerController->login(
                $dataSL['url'],
                $dataSL['port'],
                $dataSL['password'],
                $dataSL['username'],
                $dataSL['companyDB']
        );
    } catch (\Exception $e) {
        return $this->respond(['status' => 500, 'message' => 'Error login SL: ' . $e->getMessage()], 500);
    }

    if (empty($conexionSap->SessionId)) {
        return $this->respond(['status' => 500, 'message' => 'No se obtuvo SessionId'], 500);
    }

    $cookie = "B1SESSION=" . $conexionSap->SessionId . "; ROUTEID=.node1";
    $slRoot = rtrim($dataSL['url'], '/');
    if (stripos($slRoot, '/b1s/v1') === false) {
        $slRoot .= '/b1s/v1';
    } else {
        $pos = stripos($slRoot, '/b1s/v1');
        $slRoot = substr($slRoot, 0, $pos) . '/b1s/v1';
    }

    $getHeaders = [
        "Accept: application/json",
        "Content-Type: application/json",
        "User-Agent: PHP",
        "B1S-CaseInsensitive: true"
    ];

    // Header clave: le dice a Service Layer que reemplace por completo
    // la colección hija, en vez de solo actualizar/agregar elementos
    $patchHeaders = array_merge($getHeaders, [
        "B1S-ReplaceCollectionsOnPatch: true"
    ]);

    // 1) GET de los roles actuales
    $getUrl = $slRoot . "/EmployeesInfo({$empID})?" . http_build_query([
        '$select' => 'EmployeeID,EmployeeRolesInfoLines'
    ]);

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $getUrl,
        CURLOPT_PORT => $dataSL['port'],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_COOKIE => $cookie,
        CURLOPT_SSL_VERIFYHOST => false,
        CURLOPT_SSL_VERIFYPEER => false,
        CURLOPT_HTTPHEADER => $getHeaders,
        CURLOPT_TIMEOUT => 60
    ]);
    $getResp = curl_exec($ch);
    $getErr = curl_error($ch);
    $getHttp = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($getErr || $getHttp < 200 || $getHttp >= 300) {
        return $this->respond([
            'status' => 500,
            'message' => 'Error al obtener roles actuales: ' . ($getErr ?: "HTTP $getHttp: $getResp")
        ], 500);
    }

    $current = json_decode($getResp, true);
    $roles = $current['EmployeeRolesInfoLines'] ?? [];

    // 2) Filtrar quitando el rol indicado
    $newRoles = array_values(array_filter($roles, function ($r) use ($roleID) {
        return (int) ($r['RoleID'] ?? 0) !== $roleID;
    }));

    if (count($newRoles) === count($roles)) {
        return $this->respond([
            'status' => 404,
            'message' => 'El empleado no tiene asignado ese rol'
        ], 404);
    }

    // 3) PATCH con la colección ya sin ese rol + header de reemplazo total
    $patchUrl = $slRoot . "/EmployeesInfo({$empID})";
    $payload = ['EmployeeRolesInfoLines' => $newRoles];

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $patchUrl,
        CURLOPT_PORT => $dataSL['port'],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => 'PATCH',
        CURLOPT_POSTFIELDS => json_encode($payload),
        CURLOPT_COOKIE => $cookie,
        CURLOPT_SSL_VERIFYHOST => false,
        CURLOPT_SSL_VERIFYPEER => false,
        CURLOPT_HTTPHEADER => $patchHeaders,
        CURLOPT_TIMEOUT => 60
    ]);
    $resp = curl_exec($ch);
    $err = curl_error($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($err) {
        return $this->respond(['status' => 500, 'message' => 'cURL Error: ' . $err], 500);
    }

    if ($httpCode < 200 || $httpCode >= 300) {
        $body = json_decode($resp, true);
        return $this->respond(['status' => $httpCode, 'message' => 'Error al eliminar', 'body' => $body], $httpCode);
    }

    $this->log->save([
        "description" => "Eliminación de rol ID '$roleID' del empleado $empID (vía SL, EmployeesInfo/EmployeeRolesInfoLines)",
        "user" => $userName
    ]);

    // Normalizado a 200 siempre en éxito, sin importar si SAP regresó 204
    return $this->respond(['status' => 200, 'message' => 'Rol eliminado correctamente'], 200);
}

Puntos clave para recordar

• PATCH en Service Layer nunca borra por omisión. Si un elemento de una colección hija no aparece en el arreglo que envías, se conserva tal cual.
• B1S-ReplaceCollectionsOnPatch: true convierte ese comportamiento en un reemplazo completo: lo que no incluyas en el arreglo, se elimina.
• El patrón correcto para editar colecciones hijas (agregar, actualizar o quitar) sigue siendo GET → modificar en tu código → PATCH con la colección completa — la diferencia está en agregar este header cuando el objetivo es que también se eliminen elementos.
• Aplica este header únicamente en los endpoints que manipulan la colección específica; no lo agregues de forma global a todos tus PATCH contra EmployeesInfo.
• Un 204 No Content de Service Layer confirma que la petición fue válida, no que hizo lo que tú esperabas — siempre vale la pena verificar el resultado real, sobre todo mientras ajustas la lógica de colecciones hijas.

Si estás integrando otros módulos de SAP B1 vía Service Layer (órdenes de venta, líneas de documento, direcciones de socios de negocio), este mismo principio aplica: cualquier colección hija (DocumentLines, Addresses, ContactEmployees, etc.) se comporta igual ante un PATCH normal.

Si acabas de instalar PHP 8.3 en CachyOS (o cualquier derivado de Arch) desde AUR y te encontraste con una cascada interminable de errores de composer update pidiendo extensiones que “deberían venir incluidas”, esta guía es para ti. Documentando el proceso completo que seguí para dejar funcionando un proyecto CodeIgniter 4 con dependencias de facturación electrónica (CFDI).

El problema: PHP en Arch viene troceado en paquetes AUR separados

A diferencia de otras distros donde php trae casi todo integrado, en Arch/CachyOS el paquete php83 del AUR está dividido en subpaquetes independientes por extensión (php83-dom, php83-xsl, php83-mysql, etc.), todos derivados del mismo pkgbase. Esto significa dos cosas importantes:

1. Ninguna extensión “viene por defecto” — hay que instalarlas explícitamente.
2. Como comparten pkgbase, instalar una sola extensión nueva obliga a recompilar PHP completo, junto con todas las extensiones que ya tenías.

Síntoma inicial: Composer ni siquiera arranca

PHP Warning:  PHP Startup: Unable to load dynamic library 'phar'...
PHP's phar extension is missing. Composer requires it to run.

Sin phar, Composer no corre. Punto de partida obligado.

Los errores en cadena de composer update

Una vez con phar instalado, cada corrida de composer update revela otra extensión faltante:

- phpcfdi/cfdi-to-json require ext-dom * -> it is missing from your system.
- eclipxe/cfdiutils require ext-xsl * -> it is missing from your system.

Composer te va soltando las dependencias una por una, no de golpe — así que si vas resolviendo extensión por extensión, terminas recompilando PHP completo varias veces por la naturaleza del pkgbase compartido.

La solución: instalar todo en un solo lote, desatendido

En vez de ir corrigiendo extensión por extensión (y recompilar PHP 5-6 veces), la jugada es instalar de una sola vez todas las extensiones que un stack típico de CI4 + CFDI (facturación electrónica) va a necesitar:

yay -S --noconfirm --answerdiff None --answerclean All --removemake --cleanafter \
  php83-xsl php83-soap php83-bcmath php83-simplexml php83-tokenizer php83-fileinfo \
  php83-ctype php83-dom php83-xml php83-xmlreader php83-xmlwriter php83-iconv

Qué hace cada flag

Con esto, yay corre de principio a fin sin pedir intervención manual, y como todas las extensiones comparten pkgbase, PHP se recompila una sola vez con todo el set incluido — en vez de una recompilación completa por cada extensión suelta.

Por qué justo estas extensiones

Si trabajas con librerías de facturación electrónica mexicana (CFDI) vía Composer (eclipxe/cfdiutils, phpcfdi/cfditopdf, etc.), este es el patrón típico de requisitos:

• xsl, dom, xml, xmlreader, xmlwriter, simplexml — parseo y transformación de los XML del CFDI/timbrado.
• soap — comunicación con PACs (Proveedores Autorizados de Certificación) para timbrado.
• bcmath — cálculos de precisión decimal en montos, impuestos y totales.
• tokenizer, ctype, fileinfo, iconv — requisitos base de CodeIgniter 4 y de muchos paquetes Composer modernos.

Verificación final

Una vez terminada la instalación:

php83 -m | grep -Ei 'dom|xsl|soap|bcmath|xml|tokenizer|ctype|fileinfo|iconv'
composer update

Si composer update resuelve sin errores de ext-* faltante, ya está: tu entorno CachyOS queda listo para correr CodeIgniter 4 con dependencias de facturación electrónica sin más sorpresas.

Bonus: evita recompilar cada vez que necesites otra extensión

Si en el futuro te falta una extensión nueva y no quieres esperar otra compilación completa del pkgbase de PHP, vale la pena activar Chaotic-AUR, un repositorio de binarios precompilados para paquetes de AUR (incluyendo todo el árbol php83-*):

sudo pacman-key --recv-key 3056513887B78AEB --keyserver keyserver.ubuntu.com
sudo pacman-key --lsign-key 3056513887B78AEB
sudo pacman -U 'https://cdn-mirror.chaotic.cx/chaotic-aur/chaotic-keyring.pkg.tar.zst' \
               'https://cdn-mirror.chaotic.cx/chaotic-aur/chaotic-mirrorlist.pkg.tar.zst'

Y agregando al final de /etc/pacman.conf:

[chaotic-aur]
Include = /etc/pacman.d/chaotic-mirrorlist

Con eso, la próxima extensión que necesites se instala en segundos vía pacman, sin pasar por makepkg.

Resumen para el que tenga prisa: en CachyOS/Arch, PHP viene fragmentado por extensión en AUR bajo un mismo pkgbase. En vez de ir instalando una por una según te las va pidiendo Composer, identifica de una vez el set completo que necesita tu stack (CI4 + CFDI, en mi caso) e instálalo todo junto con yay -S --noconfirm --answerdiff None --answerclean All --removemake --cleanafter <paquetes>. Te ahorras varias recompilaciones completas del core de PHP.

¿Tu integración de ONLYOFFICE con Nextcloud dejó de funcionar después de renovar el certificado SSL? Aparece el error: “Error when trying to connect (Error occurred in the document service: Error while downloading the document file to be converted.)” No te preocupes, aquí tienes la guía paso a paso para resolverlo de forma definitiva, tanto si usas certificado autofirmado como si quieres migrar a Let’s Encrypt.

📌 Índice

1. Diagnóstico del problema
2. Renovar el certificado en Nextcloud (Snap)
3. Configurar Apache para el puerto 4445 (si aplica)
4. Solución de confianza SSL en el contenedor ONLYOFFICE
   • Opción A (recomendada): Agregar el certificado a la CA del contenedor
   • Opción B (temporal): Deshabilitar verificación SSL
5. Configurar la integración en Nextcloud
6. Automatizar renovaciones futuras
7. Conclusión y recomendaciones finales

1. 🔍 Diagnóstico del problema

El error se debe a que el contenedor de ONLYOFFICE Document Server no confía en el nuevo certificado que presenta Nextcloud al intentar descargar el archivo a convertir. En los logs del contenedor aparece:

error downloadFile:url=https://gusadrive.dyndns.org:444/... code:DEPTH_ZERO_SELF_SIGNED_CERT

Para confirmar el diagnóstico, revisa los logs de tu contenedor:

sudo docker ps   # Identifica el nombre del contenedor (ej. reverent_torvalds)
sudo docker logs  --tail 100 | grep -i "downloadFile\|error\|CERT"

2. 🔄 Renovar el certificado en Nextcloud (Snap)

Si aún no has renovado tu certificado autofirmado, sigue estos pasos. Si ya lo hiciste, pasa al paso 3.

a) Generar un nuevo certificado autofirmado para el dominio:

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout /var/snap/nextcloud/current/certs/custom/key.pem \
    -out /var/snap/nextcloud/current/certs/custom/cert.pem \
    -subj "/CN=gusadrive.dyndns.org"

b) Crear el archivo chain.pem (necesario para Nextcloud Snap):

sudo cp /var/snap/nextcloud/current/certs/custom/cert.pem /var/snap/nextcloud/current/certs/custom/chain.pem

c) Instalar el certificado en Nextcloud Snap:

sudo nextcloud.enable-https custom \
    /var/snap/nextcloud/current/certs/custom/cert.pem \
    /var/snap/nextcloud/current/certs/custom/key.pem \
    /var/snap/nextcloud/current/certs/custom/chain.pem

d) Reiniciar Nextcloud:

sudo snap restart nextcloud

3. 🌐 Configurar Apache para el puerto 4445 (si aplica)

Si tienes un VirtualHost de Apache que expone el panel de ONLYOFFICE en el puerto 4445, actualiza la configuración.

a) Localiza el VirtualHost:

sudo grep -r "4445" /etc/apache2/sites-enabled/

b) Edita el archivo (ej. /etc/apache2/sites-available/onlyoffice.conf) y apunta a los nuevos certificados:

<VirtualHost *:4445>
    ServerName gusadrive.dyndns.org
    SSLEngine on
    SSLCertificateFile "/etc/apache2/ssl/onlyoffice.crt"
    SSLCertificateKeyFile "/etc/apache2/ssl/onlyoffice.key"
    ...
</VirtualHost>

c) Copia los certificados a la ruta especificada:

sudo mkdir -p /etc/apache2/ssl
sudo cp /var/snap/nextcloud/current/certs/custom/cert.pem /etc/apache2/ssl/onlyoffice.crt
sudo cp /var/snap/nextcloud/current/certs/custom/key.pem /etc/apache2/ssl/onlyoffice.key

d) Habilita el sitio y reinicia Apache:

sudo a2ensite onlyoffice.conf
sudo systemctl restart apache2

4. 🐳 Solución de confianza SSL en el contenedor ONLYOFFICE

Tienes dos opciones para que el contenedor confíe en el certificado autofirmado de Nextcloud.

✅ Opción A (Recomendada para producción): Agregar el certificado al almacén de CA del contenedor

1. Copia el certificado al contenedor:

sudo docker cp /var/snap/nextcloud/current/certs/custom/cert.pem <nombre_contenedor>:/usr/local/share/ca-certificates/nextcloud.crt

2. Actualiza el almacén de CA dentro del contenedor:

sudo docker exec <nombre_contenedor> update-ca-certificates

3. Reinicia el contenedor:

sudo docker restart <nombre_contenedor>

4. Verifica que el certificado se haya agregado:

sudo docker exec <nombre_contenedor> ls -la /usr/local/share/ca-certificates/

⚠️ Opción B (Solución temporal / pruebas): Deshabilitar la verificación SSL en ONLYOFFICE

Esta opción es más rápida pero reduce la seguridad (el contenedor no validará certificados en ninguna conexión saliente).

1. Entra al contenedor:

sudo docker exec -it <nombre_contenedor> bash

2. Edita el archivo /etc/onlyoffice/documentserver/local.json y agrega la siguiente sección (si no existe):

{
  "services": {
    "CoAuthoring": {
      "requestDefaults": {
        "rejectUnauthorized": false
      }
    }
  }
}

3. Guarda, sal del contenedor y reinícialo:

sudo docker restart <nombre_contenedor>

5. ⚙️ Configurar la integración en Nextcloud

Ve a Configuración → ONLYOFFICE → Servidor de documentos en Nextcloud y asegura estos valores:

• URL del servidor de documentos: http://localhost:8085/ (con barra final).
• Clave secreta (JWT): Debe coincidir con la generada en ONLYOFFICE. Obténla con: sudo docker exec <nombre_contenedor> sudo documentserver-jwt-status.sh
• Configuración avanzada (JSON):
  • Si usaste la Opción A, no necesitas nada extra.
  • Si usaste la Opción B, agrega: { "rejectUnauthorized": false }

Guarda los cambios.

6. 🔁 Automatizar renovaciones futuras (para certificado autofirmado)

Crea un script que se ejecute mensualmente para regenerar el certificado e instalarlo tanto en Nextcloud como en el contenedor.

Script de ejemplo (/root/renew_selfsigned.sh):

#!/bin/bash
# Regenerar certificado autofirmado
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout /var/snap/nextcloud/current/certs/custom/key.pem \
    -out /var/snap/nextcloud/current/certs/custom/cert.pem \
    -subj "/CN=gusadrive.dyndns.org"

cp /var/snap/nextcloud/current/certs/custom/cert.pem /var/snap/nextcloud/current/certs/custom/chain.pem

# Instalar en Nextcloud
nextcloud.enable-https custom \
    /var/snap/nextcloud/current/certs/custom/cert.pem \
    /var/snap/nextcloud/current/certs/custom/key.pem \
    /var/snap/nextcloud/current/certs/custom/chain.pem

snap restart nextcloud

# Copiar al contenedor de ONLYOFFICE
docker cp /var/snap/nextcloud/current/certs/custom/cert.pem <nombre_contenedor>:/usr/local/share/ca-certificates/nextcloud.crt
docker exec <nombre_contenedor> update-ca-certificates
docker restart <nombre_contenedor>

Programa en cron (diario a las 3 AM, primer día de mes):

sudo crontab -e
# Añadir la línea:
0 3 1 * * /root/renew_selfsigned.sh >> /var/log/renew_cert.log 2>&1

7. 🎯 Conclusión y recomendaciones finales

• El error “Error while downloading the document file” después de renovar un certificado autofirmado en Nextcloud se debe a que el contenedor de ONLYOFFICE no confía en ese certificado.
• Opción A (recomendada): Agregar el certificado al almacén de CA del contenedor y actualizar las CA. Es segura y permite mantener la verificación SSL activa.
• Opción B (temporal): Deshabilitar la verificación SSL en ONLYOFFICE editando local.json. Más rápida pero menos segura.
• Recomendación a largo plazo: Utilizar un certificado de Let’s Encrypt con validación DNS para evitar este problema de raíz y simplificar las renovaciones.

Notas adicionales:

• La comunicación entre Nextcloud y ONLYOFFICE puede hacerse por HTTP interno (http://localhost:8085) para evitar SSL por completo (válido si ambos servicios corren en el mismo servidor).
• Asegura que el token JWT coincida exactamente entre ambos lados; un token incorrecto dará error 403.
• Los logs del contenedor son la mejor herramienta para depurar: sudo docker logs <nombre> --tail 50 -f.

¿Te ha sido útil esta guía? Déjanos un comentario si tienes dudas o comparte tu experiencia. Si necesitas ayuda adicional, no dudes en contactarnos.