Tutorial FileBrowser Quantum en la nube

En este tutorial se explica el despliegue de FileBrowser Quantum en Oracle Cloud Infrastructure (OCI). El procedimiento es igualmente válido para otros proveedores cloud o instalaciones locales, ya que la mayoría de los pasos no varían.

Con esta configuración obtendremos un espacio web auto gestionado para el almacenamiento de archivos, orientado a uso personal o colaborativo, con control total sobre los datos evitando el riesgo de exponer datos sensibles en empresas de terceros.

El entorno de partida es una instancia Ubuntu Linux con Docker y Docker Compose, que actualmente hospeda esta web pero lo puedes desplegar en cualquier otra infraestructura cloud o en local en una Raspberry o cualquier otra máquina con Linux.

¿Qué es FileBrowser Quantum?

FileBrowser Quantum es una aplicación web autoalojada que permite acceder y gestionar archivos directamente desde el navegador, con soporte para usuarios, permisos, compartición de archivos y edición de contenidos.

Es una alternativa propia a servicios como Google Drive, OneDrive o Dropbox, con la ventaja de que los datos se almacenan en tu propia infraestructura.

Se trata de un fork avanzado del proyecto open source File Browser original, con una interfaz más moderna y soporte para la integración con OnlyOffice, lo que permite abrir y editar documentos de texto, hojas de cálculo y presentaciones directamente desde el navegador. Además, ofrece funcionalidades avanzadas como la compartición de archivos mediante enlaces públicos y se encuentra en desarrollo activo, incorporando nuevas características de forma continua. En definitiva, es un servicio que transmite una clara sensación de producto profesional y bien mantenido.

REQUISITOS PREVIOS

Toda la guía paso a paso se ha realizado sobre una instancia Ubuntu Linux con el panel aaPanel instalado en Oracle Cloud Infrastructure, el mismo servidor que hospeda www.tallerdeapps.com.

Los requisitos mínimos para desplegar FileBrowser Quantum en un servidor accesible desde Internet consisten en disponer de una instancia Linux con Docker y Docker Compose. Si además se cuenta con un dominio web, es posible acceder al servicio mediante un proxy inverso utilizando un subdominio, lo que proporciona una URL más amigable que una dirección IP acompañada de un puerto. En este tutorial se utiliza aaPanel para crear el proxy inverso, aunque se puede emplear Traefik Proxy u otra tecnología equivalente según las preferencias o necesidades del entorno.

Del mismo modo, el servicio puede desplegarse en una red local, utilizando un equipo que ejecute el contenedor de FileBrowser Quantum y ofrezca acceso a los distintos ordenadores de la intranet.

Se requieren conocimientos técnicos de Linux, administración de infraestructuras en la nube, gestión de conexiones externas a instancias, así como la creación y configuración de dominios y subdominios.

Paso 1 · Estructura de directorios

Antes de desplegar FileBrowser Quantum es importante comprender la estructura de directorios que se utilizará, ya que cada uno cumple una función específica dentro del servicio.

Árbol de directorios utilizado en este tutorial:

/www/drivetallerdeapps/
│
├── data/                   ← Archivos gestionados por FileBrowser
│
├── docker-compose.yml      ← Definición del servicio Docker
│
└── config.yaml             ← Configuración de FileBrowser Quantum

/www/drivetallerdeapps/data
Directorio raíz de los archivos gestionados por FileBrowser Quantum. Todo el contenido almacenado en este directorio será accesible desde la interfaz web del servicio.
/www/drivetallerdeapps/docker-compose.yml
Archivo principal de Docker Compose. Define el contenedor, los volúmenes, los puertos y las políticas de ejecución del servicio FileBrowser Quantum.
/www/drivetallerdeapps/config.yaml
Archivo de configuración principal de FileBrowser Quantum. Contiene los ajustes del servicio, incluyendo usuarios, autenticación, permisos y el directorio raíz expuesto a través de la aplicación.

Comenzamos. Abrimos una sesión SSH en la instancia y, a continuación, se crean los directorios necesarios y se asignan los propietarios y los permisos adecuados:

Con mkdir se crean los directorios con el usuario que ejecuta el comando. En este caso, al utilizar sudo, tanto el propietario como el grupo de los directorios creados serán root.

sudo mkdir -p /www/drivetallerdeapps/data

Para que el contenedor FileBrowser Quantum tenga permisos de escritura sobre los volúmenes montados, es necesario asignar como propietario el UID 1000 y el GID 1000, que son los identificadores utilizados internamente por FileBrowser. En este entorno concreto, dicho UID corresponde al usuario opc. En otros entornos puede corresponder a otro usuario o incluso no existir como nombre en el sistema host. Los permisos seguirán funcionando correctamente, ya que Docker opera exclusivamente con identificadores numéricos (UID/GID), no con nombres de usuario.

Adicionalmente, se ajustan los permisos de lectura, escritura y ejecución necesarios mediante el comando chmod.

sudo chown -R 1000:1000 /www/drivetallerdeapps/data
sudo chmod -R 755 /www/drivetallerdeapps/data

Con el comando chown se cambia el propietario de los directorios creados al usuario con UID 1000. Este UID corresponde al usuario con el que se ejecuta FileBrowser Quantum dentro del contenedor Docker. Asignar la propiedad de los directorios a este UID garantiza que la aplicación pueda leer y escribir correctamente en el sistema de archivos montado desde el host.

Recordatorio sobre permisos en Linux del comando chmod
En sistemas Linux, los permisos de lectura, escritura y ejecución se representan mediante valores numéricos. La siguiente tabla resume su significado:

Valor	Permiso	Significado
4	r	Lectura (read)
2	w	Escritura (write)
1	x	Ejecución (execute)

Los permisos se asignan sumando estos valores para el propietario, el grupo y otros usuarios. Por ejemplo, el permiso 755 equivale a:

Propietario: 7 → lectura, escritura y ejecución (4 + 2 + 1)
Grupo: 5 → lectura y ejecución (4 + 1)
Otros: 5 → lectura y ejecución (4 + 1)

Comprobación de la creación de directorios

Si todo ha ido bien obtendremos algo como esto. El árbol de directorios con el propietario y permisos:

find /www/drivetallerdeapps -ls
  4206916      4 drwxr-xr-x   3 root     root         4096 Feb  1 21:35 /www/drivetallerdeapps
  4206926      4 drwxr-xr-x   2 opc      opc          4096 Feb  1 21:35 /www/drivetallerdeapps/data

Para comprobar que "opc" corresponde con UID y GID 1000:

id 1000
uid=1000(opc) gid=1000(opc) groups=1000(opc)

Paso 2 · Archivo de configuración

El archivo de configuración es obligatorio para que FileBrowser Quantum pueda iniciarse. En este paso utilizaremos el archivo mínimo funcional, suficiente para que el servicio arranque y permita la gestión básica de archivos y usuarios.

Este archivo debe ubicarse en la ruta que hayamos definido previamente en el docker-compose.yml. En nuestro caso:


sudo nano /www/drivetallerdeapps/config.yaml

Nota: Aunque docker-compose.yml utiliza habitualmente la extensión .yml, FileBrowser Quantum emplea específicamente el archivo config.yaml (con extensión .yaml) como archivo de configuración principal.

A continuación se muestra el contenido mínimo necesario, tal como aparece en la documentación oficial :


server:
  sources:
    - path: /folder # Do not use a root "/" directory or include the "/var" folder
      config:
        defaultEnabled: true

Explicación línea por línea

server:
Bloque principal de configuración del servidor FileBrowser Quantum.
- sources:
  Define una lista de fuentes de datos (sources), es decir, carpetas del sistema que FileBrowser expondrá a los usuarios.
  - - path: /folder
    Ruta interna del contenedor que se utilizará como raíz de archivos. Esta ruta debe coincidir con el volumen montado en el archivo docker-compose.yml.
  - config:
    Bloque de configuración específico para esta fuente.
    - defaultEnabled: true
      Indica que la fuente estará habilitada automáticamente para los usuarios. En configuraciones básicas, esto permite que los usuarios puedan acceder a su contenido sin necesidad de activarla manualmente.

Alcance de este archivo de configuración

Este archivo representa la configuración mínima necesaria para que FileBrowser Quantum funcione. Al levantar el servicio por primera vez, FileBrowser Quantum crea automáticamente un usuario administrador por defecto:

Usuario: admin
Contraseña: admin

Con este archivo mínimo config.yaml es posible:

Iniciar correctamente el servicio
Acceder al panel web con el usuario administrador
Crear nuevos usuarios y modificar credenciales del usuario admin
Gestionar archivos y carpetas

A partir de esta base, FileBrowser Quantum permite crear entornos multiusuario con carpetas privadas, carpetas compartidas y permisos avanzados. No obstante, esta configuración avanzada queda fuera del objetivo de este tutorial, que se centra en una instalación funcional y sencilla.

Otras configuraciones de usuarios desde el archivo de configuración

Opcionalmente, es posible definir un usuario administrador al crear el servicio añadiendo las propiedades adminUsername: y adminPassword: en el archivo de configuración. Sin embargo, es recomendable definir la contraseña mediante una variable de entorno para evitar exponerla directamente en el archivo config.yaml

También es posible definir configuraciones más avanzadas directamente desde el archivo config.yaml, como el uso de múltiples fuentes, reglas de acceso explícitas y entornos multiusuario complejos. Para profundizar en estos escenarios se recomienda consultar la documentación oficial:

https://filebrowserquantum.com/en/docs/advanced/source-configuration/sources/

Paso 3 · Archivo principal de Docker Compose

La configuración del contenedor se realiza mediante el archivo docker-compose.yml. Con tu editor de texto favorito —en este ejemplo se utiliza nano— se crea el archivo y se pega el contenido del fichero Docker Compose. Este archivo se ubicará en el directorio raíz del proyecto.

sudo nano /www/drivetallerdeapps/docker-compose.yml

Recuerda que los archivos YAML son muy estrictos con la indentación. Es fundamental respetar exactamente los espacios y la estructura de cada línea, ya que un error de sangrado provocará fallos al ejecutar Docker Compose.

services:
  tallerdrive:
    image: gtstef/filebrowser:stable
    container_name: drivetallerdeapps
    restart: unless-stopped

    ports:
      - "8080:80"

    volumes:
      - /www/drivetallerdeapps/data:/folder
      - ./config.yaml:/home/filebrowser/config.yaml:ro

services: Define los servicios que serán gestionados por Docker Compose.
tallerdrive: Nombre lógico del servicio dentro del stack de Docker Compose.
image: Imagen Docker utilizada para crear el contenedor (FileBrowser Quantum).
container_name: Nombre explícito asignado al contenedor Docker.
restart: Política de reinicio automático del contenedor. Indica a Docker que el contenedor se reinicie automáticamente en la mayoría de los casos, excepto cuando se detiene manualmente.
ports: Define el mapeo de puertos entre el sistema anfitrión y el contenedor.
- 8080:80 Expone el puerto 80 del contenedor en el puerto 8080 del sistema anfitrión.
volumes: Define los volúmenes persistentes utilizados por el contenedor.
- /www/drivetallerdeapps/data:/folder Directorio del sistema anfitrión que se monta como carpeta de archivos accesible desde FileBrowser.
- ./config.yaml:/home/filebrowser/config.yaml Archivo de configuración principal de FileBrowser Quantum.

Nuevamente, nos ceñimos al ejemplo más básico de la documentación oficial. Es preferible comenzar con una versión simple y, si todo funciona correctamente y se necesita alguna funcionalidad adicional, consultar la documentación y experimentar a partir de ella.

Paso 4 · Apertura del puerto de FileBrowser Quantum

En este ejemplo, el servicio FileBrowser se ha configurado para utilizar el puerto 8080 del sistema anfitrión. Este puerto se ha elegido únicamente a modo de ejemplo y puede modificarse según las necesidades de cada instalación.

En un escenario recomendado, FileBrowser no se expone directamente a Internet. El acceso se realiza a través de un proxy inverso que escucha en los puertos estándar 80 y 443. En este caso, el puerto 8080 se utiliza únicamente para la comunicación interna entre el proxy inverso y el contenedor Docker, preferiblemente enlazado a la interfaz de loopback (127.0.0.1).

Cuando el puerto se enlaza exclusivamente a 127.0.0.1, no es necesario abrirlo ni en el firewall local de la instancia ni en las reglas de seguridad del proveedor cloud, ya que el servicio no será accesible desde el exterior.

Nota importante: Docker gestiona sus propias reglas de iptables para la publicación de puertos. Esto implica que un puerto puede quedar accesible aunque no exista una regla explícita en UFW. Por este motivo, UFW no debe considerarse una protección suficiente para servicios Docker expuestos directamente. Cuando se inicia un contenedor que publica puertos, Docker crea dinámicamente reglas de iptables en memoria, sin necesidad de abrir manualmente el puerto en el firewall de la instancia.

En caso de no disponer de un dominio o subdominio y necesitar acceder al servicio directamente mediante http://IP_DEL_SERVIDOR:8080, será necesario:

Publicar el puerto en Docker sin limitarlo a 127.0.0.1
Crear una regla de entrada en el proveedor cloud (Oracle Cloud Infrastructure u otro). Puedes consultar el siguiente tutorial sobre la configuración de reglas de seguridad en OCI: Configuración de reglas de seguridad en Oracle Cloud Infrastructure
Permitir el puerto en el firewall del sistema operativo, si aplica

En el caso concreto de esta instancia, se ha creado una regla de entrada específica para el puerto 8080 en la sección Network Security Group del panel de Oracle Cloud Infrastructure, permitiendo el acceso externo al servicio. En OCI, esta configuración se gestiona desde la sección Network Security Groups del VCN, donde se definen reglas de ingreso (ingress) indicando el protocolo (TCP), el puerto (8080) y el rango de origen (CIDR).

Para ampliar información, puedes consultar la documentación oficial de Oracle: Crear Network Security Groups en OCI . También dispones de una guía paso a paso en esta misma web donde se explica en detalle cómo configurar correctamente el firewall en Oracle Cloud Infrastructure.

Si utilizas otras infraestructuras en la nube, el procedimiento es muy similar:

Amazon Web Services (AWS) — en la consola de AWS debes ir al servicio EC2 (o al panel de VPC → Security groups), seleccionar el Security Group asociado a tu instancia y editar Inbound rules para añadir una regla TCP al puerto 8080 (o el que uses) con el origen adecuado. Documentación oficial: Crear Security Group (EC2)
Google Cloud (GCP) — en la consola de GCP ve a VPC network → Firewall (o VPC networks → seleccionar la red → pestaña Firewalls) y crea una regla de firewall de tipo Ingress indicando protocolo TCP y el puerto 8080, junto con el rango de IPs origen que quieras permitir. Documentación oficial: Firewall rules (VPC) en Google Cloud

Nota de seguridad importante: Este acceso directo solo se recomienda para entornos de pruebas o uso puntual y no es aconsejable en entornos de producción.

En las próximas partes de esta guía se explica cómo configurar el acceso al servicio de una forma más segura y profesional.

services:
  tallerdrive:
    .
    ports:
      # Opción 1: acceso directo (no recomendado en producción)
      - "8080:80"
      # FileBrowser es accesible directamente desde http://IP_DEL_SERVIDOR:8080

      # Opción 2: acceso solo local (recomendado)
      - "127.0.0.1:8080:80"
      # FileBrowser solo es accesible desde el propio servidor y debe usarse junto a un proxy inverso
      # (requiere dominio o subdominio para el acceso externo)

Paso 5 · Arranque y comprobación local

Una vez creada la estructura de directorios, el archivo de configuración y el fichero docker-compose.yml, ya es posible iniciar el servicio FileBrowser Quantum por primera vez.

Para ello, nos situamos en el directorio raíz del proyecto y ejecutamos Docker Compose en segundo plano:

cd /www/drivetallerdeapps
sudo docker compose up -d

Si todo es correcto, Docker descargará la imagen de FileBrowser Quantum (si no está presente en el sistema) y creará el contenedor definido en el archivo docker-compose.yml.

El parámetro -d indica que el contenedor se ejecuta en segundo plano (detached mode), permitiendo que la sesión SSH continúe disponible.

Comprobación del estado del contenedor

Para verificar que el contenedor se ha creado correctamente y se encuentra en ejecución, se puede utilizar el siguiente comando:

sudo docker ps

La salida debería mostrar un contenedor con un nombre similar a: drivetallerdeapps y con el estado Up.

CONTAINER ID   IMAGE                    COMMAND              STATUS          PORTS                  NAMES
a1b2c3d4e5f6   gtstef/filebrowser:stable "/entrypoint.sh"    Up 10 seconds   0.0.0.0:8080->80/tcp   drivetallerdeapps

Si el contenedor no aparece o se detiene inmediatamente tras iniciarse, es recomendable revisar los logs para identificar el motivo del fallo.

Revisión de logs del contenedor

Para consultar los mensajes generados por FileBrowser Quantum durante el arranque, se utiliza el siguiente comando:

sudo docker logs --tail 30 drivetallerdeapps
# Muestra las últimas 30 entradas del log del contenedor drivetallerdeapps

En un arranque correcto, se mostrarán mensajes indicando la carga del archivo config.yaml, la inicialización del servidor y la escucha en el puerto interno 80.

Si existe algún error de configuración (por ejemplo, un archivo YAML mal indentado o una ruta incorrecta), el contenedor mostrará mensajes de error claros y se detendrá automáticamente.

Errores frecuentes en este paso

Indentación incorrecta en docker-compose.yml o config.yaml
Ruta incorrecta del archivo config.yaml dentro del contenedor
Permisos insuficientes sobre el directorio /www/drivetallerdeapps/data
Puerto ya ocupado por otro servicio

Comprobación del acceso local

Si el contenedor se encuentra en ejecución, es posible comprobar el acceso local al servicio desde el propio servidor. Para ello, se puede utilizar un navegador web o una herramienta de línea de comandos como curl.

Desde el propio servidor:

curl http://localhost:8080

Si el servicio está funcionando correctamente, se devolverá código HTML correspondiente a la interfaz web de FileBrowser Quantum.

En este punto, el servicio ya está correctamente desplegado y funcionando a nivel local. En el siguiente paso se comprobará el acceso web desde Internet y el inicio de sesión en la interfaz gráfica.

Paso 6 · Acceso web desde Internet

Una vez verificado que el servicio funciona correctamente en local, el siguiente paso consiste en comprobar el acceso a FileBrowser Quantum desde Internet.

Si se ha configurado el acceso directo y el puerto 8080 está correctamente publicado en Docker y permitido en las reglas de seguridad del proveedor cloud, el servicio será accesible desde un navegador web mediante la siguiente URL:

http://IP_DEL_SERVIDOR:8080

Al acceder a dicha dirección, se mostrará la pantalla de inicio de sesión de FileBrowser Quantum solicitando usuario y contraseña.

Usuario: admin
Contraseña: admin

Nota: Se recomienda cambiar la contraseña del usuario administrador inmediatamente tras el primer acceso desde el panel de configuración.

Tras iniciar sesión, accederemos a la interfaz principal de FileBrowser Quantum, donde se mostrará un mensaje de bienvenida junto con una advertencia indicando que la base de datos de usuarios ha sido creada de nuevo.

En esta versión mínima orientada a pruebas y aprendizaje, este comportamiento es normal, ya que todavía no se ha configurado un volumen persistente para almacenar la base de datos interna del servicio. Por el momento, este aviso puede ignorarse con seguridad.

Más adelante, en esta misma guía paso a paso, se mostrará cómo implementar un archivo docker-compose.yml y un config.yaml más completos, con ajustes muy recomendables para entornos de producción, incluyendo la persistencia de usuarios y configuraciones.

Paso 7 · Limpieza del entorno del contenedor

Si durante el proceso se han producido mensajes de error o se han realizado cambios en la configuración, antes de volver a levantar el servicio con los ajustes aplicados es recomendable asegurar un estado limpio del entorno. Para ello, se puede detener y eliminar el contenedor y recrearlo a partir de la configuración actual.

El siguiente comando detiene y elimina el contenedor indicado. Si el contenedor no existe o se produce algún error, Docker mostrará el mensaje correspondiente:


sudo docker rm -f drivetallerdeapps

Este comando no elimina:

Las imágenes Docker
Los volúmenes montados explícitamente en el contenedor

Importante: Con la configuración mínima utilizada en este tutorial, FileBrowser Quantum no tiene persistido su almacenamiento interno de datos. Por este motivo, al eliminar el contenedor se pierden los usuarios creados, sus configuraciones y reglas de acceso, quedando únicamente el usuario administrador por defecto (admin / admin) al volver a iniciar el servicio.

No obstante, los archivos y directorios subidos o creados por los usuarios se conservan, ya que estos se almacenan en el volumen de datos montado en /folder (directorio data en el sistema anfitrión). En este ejemplo mínimo, la reinicialización afecta únicamente a la gestión de usuarios y permisos, no al contenido de los archivos.

Tras eliminar el contenedor, el servicio puede iniciarse nuevamente con:


sudo docker compose up -d

Esta práctica resulta útil durante fases de pruebas o aprendizaje, ya que permite recrear el servicio desde cero de forma controlada. En entornos de producción es imprescindible configurar volúmenes persistentes adicionales para conservar usuarios y configuraciones.

Paso 8 · Configurar usuarios y gestionar archivos desde el panel

Al iniciar sesión por primera vez con el usuario admin, desde el botón de Configuración (icono de la rueda dentada) se accede al menú Users Management. Desde este panel, de forma intuitiva, es posible crear y eliminar usuarios, asignar permisos (lectura, escritura, compartir, etc.) y definir un directorio inicial que delimita el alcance de visibilidad dentro del directorio de datos.

Asimismo, se puede editar el propio usuario admin para modificar su contraseña, directorios asignados u otros parámetros de seguridad.

Gestión de usuarios y permisos

Desde el panel de control de FileBrowser Quantum es posible:

Crear nuevos usuarios
Asignar carpetas privadas mediante el scope del usuario
Conceder acceso manual a carpetas compartidas mediante Access Management

Estas opciones permiten construir entornos mixtos, combinando usuarios aislados con recursos compartidos, aunque requieren una configuración más detallada para garantizar la seguridad y el control de accesos.

El usuario admin dispone de acceso completo al sistema, lo que permite realizar todas las operaciones desde el panel de control: gestión de archivos, creación y administración de usuarios, asignación de permisos y configuración avanzada.

Importante: por motivos de seguridad, se recomienda cambiar la contraseña del usuario admin inmediatamente tras el primer inicio de sesión.

Además, desde el panel de configuración se pueden ajustar otros parámetros generales, como el idioma predeterminado, opciones de interfaz, comportamiento del sistema y preferencias relacionadas con la experiencia de usuario.

Ten en cuenta que no es objetivo de esta guía detallar todas las posibilidades y opciones del panel de administración de FileBrowser. En este tutorial nos centramos principalmente en el despliegue y puesta en marcha del servicio, dejando la configuración avanzada y el uso detallado del panel para documentación específica o guías posteriores.

En lo que respecta a la interfaz de usuario, FileBrowser Quantum ofrece una experiencia moderna y fácil de usar. Por ejemplo, para subir archivos basta con arrastrarlos al interior de la ventana. Además, mediante el botón derecho del ratón se accede a distintas opciones, como renombrar, compartir o eliminar archivos y carpetas. A pesar de ser una aplicación totalmente gratuita, presenta un aspecto visual muy profesional.

Paso 9 · Permisos y uso de WinSCP

El directorio de datos de FileBrowser Quantum (/www/drivetallerdeapps/data) pertenece al usuario y grupo con UID/GID 1000, que es el identificador utilizado internamente por el contenedor. Por este motivo, el usuario del sistema ubuntu no dispone de permisos de escritura por defecto.

Este comportamiento es correcto y esperado. Si se intenta subir o editar archivos mediante WinSCP o una sesión SSH sin ajustar los permisos, se obtendrá un error de Permiso denegado.

La solución adecuada consiste en añadir el usuario utilizado para la conexión SSH (ubuntu en este ejemplo) al mismo grupo que utiliza FileBrowser (GID 1000) y ajustar el grupo propietario del directorio de datos para permitir la escritura compartida de forma segura.

Identificar el grupo con GID 1000

En primer lugar, se comprueba qué grupo corresponde al identificador 1000:

getent group 1000

Salida típica en una instancia Ubuntu sobre Oracle Cloud:

opc:x:1000:

En este entorno, el grupo con GID 1000 se denomina opc. El nombre puede variar según la distribución o proveedor cloud, pero el identificador numérico (1000) es lo relevante.

Añadir el usuario SSH al grupo de FileBrowser

sudo usermod -aG opc ubuntu

Tras ejecutar este comando es necesario cerrar y volver a abrir la sesión SSH para que los cambios de grupo tengan efecto.

Ajustar permisos del directorio de datos

sudo chown -R :opc /www/drivetallerdeapps/data
sudo chmod -R 775 /www/drivetallerdeapps/data
sudo chmod g+s /www/drivetallerdeapps/data

Con estos ajustes:

El contenedor FileBrowser (UID/GID 1000) puede leer y escribir.
El usuario ubuntu puede gestionar archivos desde WinSCP o SSH.
No se utilizan permisos inseguros como chmod 777.

El bit g+s (Set Group ID) aplicado sobre el directorio garantiza que todos los archivos y subdirectorios creados dentro hereden automáticamente el grupo opc, manteniendo la coherencia de permisos a lo largo del tiempo.

Comprobación final

ls -ld /www/drivetallerdeapps/data

Resultado esperado:

drwxrwsr-x 2 opc opc 4096 Feb 11 22:38 /www/drivetallerdeapps/data

A partir de este momento, FileBrowser Quantum y WinSCP pueden operar simultáneamente sobre el mismo directorio sin conflictos de permisos.

Paso 10 · DNS / Sitio web / Certificado SSL / Reverse Proxy

Para dar un toque más profesional al servicio y, además, mejorar la seguridad, es recomendable asignar un dominio o subdominio al contenedor. De esta forma, la URL será mucho más amigable que acceder mediante una dirección IP con un puerto y evitaremos exponer directamente dicho puerto al exterior.

En este apartado se explica la secuencia de operaciones necesaria para asociar el dominio al contenedor utilizando el proxy inverso desde el panel aaPanel:

Configuración del DNS
Creación del sitio web en aaPanel. Será una mínima página web que nunca se servirá, necesaria únicamente para validar el SSL.
Configuración del certificado SSL para el dominio, tanto para HTTP como para HTTPS
Configuración del proxy inverso, que actuará como intermediario entre el dominio y el contenedor

1. Configuración del DNS

En este ejemplo real, desde el proveedor del dominio se añade un nuevo registro DNS de tipo A, que asociará un subdominio a la dirección IP pública de la instancia donde se ejecuta el servicio.

El procedimiento es muy similar en todos los proveedores de gestión de dominios. La siguiente captura corresponde a Hostinger, pero la configuración apenas varía en otros servicios. Al añadir en el registro A el nombre drive y la dirección IP del servidor, estamos creando el subdominio http://drive.tallerdeapps.com.

Los campos que debemos rellenar son:

Tipo: A. Indica que el registro apunta a una dirección IPv4.
Nombre: drive. Es el nombre del subdominio que queremos crear.
Apunta a: 144.24.195.42. Dirección IP pública del servidor al que queremos que resuelva el subdominio (en este caso, drive.tallerdeapps.com).
TTL: 300 / Auto. Tiempo de vida del registro (en segundos), es decir, cuánto tiempo los servidores DNS y los clientes cachean esta información antes de volver a consultarla. Un valor bajo permite que los cambios se propaguen más rápido.

Para comprobar que el dominio se resuelve correctamente, podemos usar el siguiente comando:

ping drive.tallerdeapps.com

Haciendo ping a drive.tallerdeapps.com [144.24.195.42] con 32 bytes de datos:
Respuesta desde 144.24.195.42: bytes=32 tiempo=11ms TTL=54
Respuesta desde 144.24.195.42: bytes=32 tiempo=10ms TTL=54
Respuesta desde 144.24.195.42: bytes=32 tiempo=11ms TTL=54
Respuesta desde 144.24.195.42: bytes=32 tiempo=14ms TTL=54

Estadísticas de ping para 144.24.195.42:
    Paquetes: enviados = 4, recibidos = 4, perdidos = 0
    (0% perdidos),
Tiempos aproximados de ida y vuelta en milisegundos:
    Mínimo = 10ms, Máximo = 14ms, Media = 11ms

Ten en cuenta que la propagación DNS no es inmediata. Puede tardar desde unos segundos hasta varias horas, aunque normalmente se resuelve en poco tiempo.

2. Creación del sitio web en aaPanel

En este caso, el servidor utiliza Ubuntu con aaPanel, por lo que se empleará este panel para crear el sitio web base sobre el que posteriormente se configurará el certificado SSL y el proxy inverso.

Si utilizas otro panel de control o una configuración manual con Nginx o Apache, el procedimiento será conceptualmente similar.

2.1 Crear el sitio web (sin proxy)

Primero se crea el sitio web básico, sin proxy, ya que es un requisito previo para la emisión del certificado SSL. Desde aaPanel en el menú Website pulsamos el botón Add site y rellenamos los campos:

Domain: drive.tallerdeapps.com
Root: /www/wwwroot/drive.tallerdeapps.com
PHP / DB / FTP: desactivados

Guardar los cambios con

2.2 Nota sobre el DocumentRoot y los archivos index generados por aaPanel

Al crear un sitio web en aaPanel, el panel genera automáticamente una estructura mínima dentro del DocumentRoot, incluyendo archivos como index.html o 404.html. Este comportamiento es normal y necesario para que el dominio responda correctamente por HTTP.

Estos archivos cumplen una función importante en las fases iniciales de la configuración, especialmente para:

Verificar que el dominio apunta correctamente al servidor
Permitir la validación de certificados SSL mediante Let’s Encrypt (file verification)
Evitar errores HTTP durante la creación del sitio

Una vez configurado el proxy inverso, el servidor web deja de servir contenido desde el sistema de archivos local. En su lugar, cuando se accede al servidor mediante la URL del subdominio (https://drive.tallerdeapps.com), el proxy inverso redirige todas las peticiones entrantes al servicio interno definido en el Target URL, en este caso http://127.0.0.1:8080, que corresponde al puerto expuesto por el contenedor.

Los archivos generados en el DocumentRoot seguirán existiendo y siendo necesarios durante la fase de validación del dominio y del certificado SSL, aunque no se utilicen para servir contenido una vez activo el proxy inverso.

En el punto en el que nos encontramos, si accedemos a http://drive.tallerdeapps.com, se mostrará la página mínima recién creada por aaPanel. Es importante fijarse en el detalle de que el acceso se realiza mediante HTTP; si intentamos acceder por HTTPS, el resultado en este momento no será el esperado, ya que el certificado SSL aún no ha sido configurado.

3. Configuración del certificado SSL

En este apartado se configura el certificado SSL para el dominio, lo que permitirá servir el sitio de forma segura mediante HTTPS. Este paso debe completarse antes de configurar el proxy inverso.

3.1 Verificar acceso HTTP (requisito para SSL)

Antes de generar el certificado SSL, es imprescindible comprobar que el sitio responde correctamente por HTTP, ya que Let’s Encrypt necesita validar el dominio.

La página debe mostrarse correctamente y no debe forzar HTTPS todavía. En este punto es normal que el acceso por HTTPS no funcione.

3.2 Crear y aplicar el certificado SSL

Acceder desde aaPanel a:

Menú lateral → Website → seleccionar la web drive.tallerdeapps.com → botón SSL

A continuación, en el menú horizontal, seleccionar la pestaña Let’s Encrypt.

Configurar Let’s Encrypt con los siguientes valores:

Application Method: File verification
Domain name: drive.tallerdeapps.com (sustituir por tu dominio)

La siguiente captura resume claramente esta secuencia de configuración:

Una vez emitido el certificado tras pulsar el botón Apply, se muestran la clave privada y el certificado.

Cambiamos a la pestaña Current Certs y activamos la opción de forzar HTTPS para que el servidor redirija automáticamente las entradas realizadas por HTTP hacia HTTPS.

Force HTTPS [activo]

Finalmente, pulsamos el botón Save para guardar la configuración.

3.3 Verificación del certificado SSL

Para comprobar que los archivos del certificado se han generado correctamente, ejecutar el siguiente comando en el servidor:

ls -l /www/server/panel/vhost/cert/drive.tallerdeapps.com/
total 8
-rw-r--r-- 1 root root 3607 Feb  8 09:26 fullchain.pem
-rw-r--r-- 1 root root 1704 Feb  8 09:26 privkey.pem

A partir de este momento, el dominio ya es accesible tanto por HTTP como por HTTPS. No obstante, seguirá mostrándose la página web mínima creada por aaPanel, ya que el proxy inverso aún no ha sido configurado.

3.4 Reiniciar el servidor web

Se recomienda reiniciar el servicio web para asegurar que la configuración del certificado SSL se aplica correctamente. En este ejemplo concreto no fue necesario, ya que el certificado se activó de forma inmediata.

Si utilizas aaPanel, puedes reiniciar los servicios web con el siguiente comando:

bt restart

Dependiendo del stack utilizado, puede ser necesario reiniciar Apache o Nginx de forma específica.

En este punto, el acceso por HTTPS ya funciona correctamente, pero el sitio seguirá mostrando la web mínima hasta completar el último paso: la configuración del proxy inverso.

4. Configuración del proxy inverso

Una vez configurado el certificado SSL, se procede a crear el proxy inverso, que permitirá redirigir el tráfico HTTPS hacia el servicio interno del contenedor, evitando exponer directamente el puerto de la aplicación.

4.1 Crear el Reverse Proxy

En esta guía se utiliza el reverse proxy integrado en aaPanel, que permite una configuración sencilla y centralizada desde el panel de control. En entornos con un número elevado de contenedores Docker o infraestructuras más dinámicas, puede ser recomendable valorar el uso de soluciones como Traefik Proxy.

En este caso se ha optado por aaPanel por su enfoque más simple y controlado, adecuado para servidores con pocos servicios y configuración manual.

Desde aaPanel:

Website → drive.tallerdeapps.com → Reverse Proxy → botón Add Reverse Proxy

Configuración:

Proxy name: filebrowserquantum (es solo una etiqueta identificativa)
Proxy dir: /
Target URL: http://127.0.0.1:8080
Sent Domain: $host
Cache: desactivado
URL rewrite: desactivado
Advanced features: desactivado

La siguiente captura muestra cómo queda la pantalla de configuración del proxy inverso:

En el campo Sent Domain se mantiene el valor por defecto $host. Esta variable indica al servidor web utilizado (Apache o Nginx) que reenvíe al servicio interno el mismo nombre de dominio utilizado por el cliente en la petición original.

De este modo, cuando se accede a https://drive.tallerdeapps.com, el proxy inverso redirige la petición a http://127.0.0.1:8080, manteniendo el dominio original en la cabecera Host. Esto permite que la aplicación del contenedor funcione correctamente detrás del proxy inverso.

Al guardar la configuración, el Reverse Proxy queda habilitado y ya es posible acceder a la aplicación desde la URL https://drive.tallerdeapps.com, utilizando el certificado SSL configurado previamente.

Si se pulsa sobre el icono del candado en la barra del navegador, cualquier usuario puede comprobar que la conexión es segura y que el certificado SSL es válido, lo cual aporta confianza y valor añadido al servicio.

La renovación del certificado SSL se gestiona automáticamente desde aaPanel. Al utilizar Let’s Encrypt, el panel programa la renovación del certificado antes de su fecha de expiración, sin necesidad de intervención manual.

Esta renovación automática funciona de forma independiente al proxy inverso y a los contenedores Docker, siempre que el dominio siga apuntando al servidor y el sitio web permanezca activo en aaPanel.

Paso 11 · Mejorando FileBrowser Quantum (persistencia, seguridad y branding)

Hasta este punto, FileBrowser Quantum se ha desplegado utilizando la configuración mínima funcional descrita en la documentación oficial. Este enfoque es ideal para aprender, probar el servicio y validar su funcionamiento, pero no es el más adecuado para un uso continuado o semi-productivo.

En este paso se introduce una versión mejorada del despliegue, incorporando una serie de ajustes muy recomendables para entornos reales, sin perder la simplicidad del stack Docker utilizado hasta ahora.

Las mejoras que se aplican son:

Persistencia de la base de datos interna de usuarios y configuraciones.
Exposición del servicio únicamente a través de la interfaz de loopback, utilizando un puerto no estándar del sistema anfitrión.
Personalización básica del branding de la aplicación: se modifica el nombre visible de la aplicación (TallerDrive), se personalizan el icono de la pantalla de inicio de sesión y el favicon del navegador, y se define una etiqueta meta description para su uso en buscadores.

11.1 Persistencia de usuarios y configuración

En la configuración utilizada hasta ahora, FileBrowser Quantum almacena su base de datos interna dentro del propio contenedor Docker. Esto implica que, al eliminar o recrear el contenedor, se pierden los usuarios, contraseñas y configuraciones. En entornos de desarrollo o pruebas, comenzar desde cero puede resultar incluso ventajoso; sin embargo, en instalaciones más completas orientadas a un uso real o de producción, este comportamiento no es deseable, ya que provoca la pérdida total de usuarios y credenciales cada vez que el servicio se reinicia o se vuelve a desplegar.

Para evitar esta situación, es necesario montar un volumen persistente en la ruta interna del contenedor Docker donde FileBrowser Quantum almacena su base de datos:

/home/filebrowser/database

Esta ruta ya existe dentro del contenedor y no debe crearse manualmente en el sistema anfitrión. Mediante Docker Compose, se enlazará con un directorio del host, permitiendo que la base de datos de usuarios y configuraciones se conserve incluso si el contenedor se elimina o se vuelve a crear.

Al igual que se hizo con el directorio data, que alberga los archivos gestionados por los usuarios, se crea un nuevo directorio database destinado a almacenar la información interna del servicio: usuarios, contraseñas, configuraciones y reglas de acceso.

Para que este directorio pueda ser utilizado correctamente por FileBrowser Quantum, se asigna como propietario y grupo el usuario con UID 1000, que es el identificador utilizado por la aplicación dentro del contenedor. Los permisos se establecen en 755, una opción adecuada y segura frente al uso indiscriminado de permisos 777.


sudo mkdir -p /www/drivetallerdeapps/database
sudo chown -R 1000:1000 /www/drivetallerdeapps/database
sudo chmod -R 755 /www/drivetallerdeapps/database

Dado que el directorio de la base de datos debe ser accesible desde el contenedor, es necesario declararlo como volumen persistente. Para ello, se modifica el archivo docker-compose.yml añadiendo el volumen correspondiente:

services:
  tallerdrive:
    image: gtstef/filebrowser:stable
    container_name: drivetallerdeapps
    restart: unless-stopped

    ports:
      - "8080:80"

    volumes:
      - /www/drivetallerdeapps/data:/folder
      - ./config.yaml:/home/filebrowser/config.yaml:ro
      - /www/drivetallerdeapps/database:/home/filebrowser/database # Volumen persistente para la base de datos de usuarios

Por último, en el archivo config.yaml se indica explícitamente la ruta del archivo de base de datos que FileBrowser Quantum debe utilizar:

server:
  database: "database/database.db" # Ruta al archivo de la base de datos
  sources:
    - path: /folder # Do not use a root "/" directory or include the "/var" folder
      config:
        defaultEnabled: true

Al levantar el contenedor, en el momento en que se accede por primera vez con el usuario administrador predeterminado (admin), FileBrowser Quantum crea automáticamente el archivo de la base de datos en el directorio /database del sistema anfitrión. Este archivo será persistente ante reinicios o paradas del servicio y podrá utilizarse para realizar copias de seguridad. Nota: Antes del primer acceso, el archivo de base de datos no existe, ya que se genera de forma automática durante la inicialización inicial del servicio.

11.2 Exposición segura del servicio (solo loopback)

En entornos de producción o semi-producción, FileBrowser Quantum no debería exponerse directamente a Internet. El acceso debe realizarse siempre a través de un proxy inverso.

En esta versión mejorada:

El contenedor escucha internamente en el puerto 80
El puerto se enlaza exclusivamente a 127.0.0.1
No es necesario abrir ningún puerto en el firewall ni en el proveedor cloud

El acceso externo se realiza únicamente a través del dominio configurado en el reverse proxy (aaPanel, Traefik, Nginx, etc.). En este ejemplo en https://drive.tallerdeapps.com

En el archivo mínimo de docker-compose.yml el apartado ports se encontraba configurado de la siguiente forma:

ports:
  - "8080:80"

Aunque esta configuración funciona correctamente, no es la más adecuada, ya que el servicio queda expuesto en todas las interfaces de red del servidor, permitiendo conexiones desde cualquier dirección IP.

Para evitar este comportamiento, se debe restringir la publicación del puerto a la interfaz de loopback, sustituyendo la configuración anterior por la siguiente:

ports:
  - "127.0.0.1:8080:80"

De este modo, Docker solo acepta conexiones locales al puerto 8080, que son las utilizadas por el proxy inverso. El servicio deja de estar accesible directamente desde Internet, aumentando significativamente el nivel de seguridad del despliegue.

Nota: Tras modificar el archivo docker-compose.yml, al detener y volver a arrancar el contenedor ya no será posible acceder directamente al servicio utilizando la IP pública como URL. Esta configuración es intencionada y forma parte de una buena práctica de seguridad.

Durante la fase de configuración, resulta recomendable relanzar la aplicación tras cada cambio realizado. De este modo, es más sencillo detectar errores de forma temprana y verificar que la nueva configuración se aplica correctamente.

11.3 Personalización del branding: iconos y nombre de la APP

FileBrowser Quantum permite personalizar algunos elementos visuales básicos desde el archivo config.yaml, lo que resulta útil para dar una identidad propia al servicio. Desplegar la aplicación con un logo corporativo y un nombre de aplicación personalizado aporta un valor añadido y una sensación de producto más profesional.

El archivo del logo se almacenará en un directorio específico dentro de la raíz del proyecto. Por los mismos motivos que en el resto de archivos y directorios utilizados por FileBrowser Quantum, se asigna como propietario el UID 1000 y se establecen permisos 755, garantizando que la aplicación pueda acceder al recurso sin comprometer la seguridad del sistema.

sudo mkdir -p /www/drivetallerdeapps/branding
sudo chown -R 1000:1000 /www/drivetallerdeapps/branding
sudo chmod -R 755 /www/drivetallerdeapps/branding

En este ejemplo, el archivo del logo debe colocarse en la siguiente ruta del sistema anfitrión:

/www/drivetallerdeapps/branding/logo.png

Si el archivo se sube mediante WinSCP u otra herramienta externa, es habitual que quede con el usuario del sistema que realiza la subida como propietario. Por ejemplo:

ls -l branding/
total 16
-rw-rw-r-- 1 ubuntu ubuntu 14165 Feb 11 20:54 logo.png

En este caso, el archivo pertenece al usuario ubuntu, utilizado por WinSCP, y es legible tanto por el grupo como por otros usuarios. Dado que FileBrowser Quantum se ejecuta con el UID 1000, basta con que el archivo tenga permisos de lectura y que el directorio permita el acceso para que la aplicación pueda utilizarlo correctamente.

11.4 Docker Compose – versión mejorada

A continuación se muestra el archivo docker-compose.yml actualizado, sustituyendo al utilizado en los pasos anteriores.

services:
  tallerdrive:
    image: gtstef/filebrowser:stable
    container_name: drivetallerdeapps
    restart: unless-stopped

    ports:
      - "127.0.0.1:8080:80" # Cambio: interfaz de entrada limitada a loopback

    volumes:
      - /www/drivetallerdeapps/data:/folder
      - /www/drivetallerdeapps/database:/home/filebrowser/database # Cambio: volumen persistente para la base de datos de usuarios
      - /www/drivetallerdeapps/branding:/home/filebrowser/branding:ro # Cambio: volumen para gráficos personalizados (solo lectura)
      - ./config.yaml:/home/filebrowser/config.yaml:ro

Cambios clave con respecto a la versión básica anterior:

Puerto accesible únicamente desde la interfaz de loopback.
Persistencia de la base de datos interna de usuarios y configuraciones, controlada mediante una propiedad específica en el archivo config.yaml, que se verá en los siguientes apartados.
Soporte para branding personalizado (nombre de la aplicación, nueva imagen en la pantalla de inicio de sesión y nuevo icono reducido en la pestaña del navegador). Las imágenes pueden estar en varios formatos comunes (PNG, JPEG, WebP, GIF, entre otros). Se recomienda un tamaño de 256x256 píxeles para una mayor compatibilidad. El tamaño del logotipo en la pantalla de inicio de sesión no es configurable desde config.yaml, ya que la aplicación lo escala internamente a un tamaño fijo.
Definición de la propiedad description utilizada como etiqueta meta description para los motores de búsqueda.

Nota: La ubicación física de las imágenes de branding se define como un volumen en docker-compose.yml. Para que la aplicación las utilice, es necesario además referenciar la ruta y el nombre de cada imagen en el archivo config.yaml bajo las propiedades correspondientes (favicon: y loginIcon:), que se describen a continuación.

11.5 Archivo `config.yaml` – versión mejorada

Para que los cambios de branding se reflejen en el servicio es necesario añadir un apartado en el archivo config con la ruta del logo personalizado.

server:
  database: "database/database.db"
  sources:
    - path: /folder # Do not use a root "/" directory or include the "/var" folder
      config:
        defaultEnabled: true
frontend:
  name: "TallerDrive"
  description: "Almacenamiento seguro de archivos en el servidor de Tallerdeapps.com"
  favicon: "/home/filebrowser/branding/logo.png"
  loginIcon: "/home/filebrowser/branding/logo.png"

11.6 Aplicar los cambios

Ya está todo listo para comprobar que los cambios se reflejan correctamente en el servicio. Si no se producen errores, a partir de este momento los datos de usuarios serán persistentes, el contenedor solo escuchará en la interfaz de loopback y se habrán aplicado las personalizaciones gráficas de la pantalla de inicio de sesión, así como el nombre del servicio.

Para aplicar la nueva configuración, es necesario detener el contenedor actual y volver a levantar el servicio, tal y como ya se ha hecho en varias ocasiones a lo largo del tutorial. Nota: docker compose up -d recrea automáticamente los contenedores si detecta cambios.

docker compose stop
sudo docker compose up -d

Al acceder nuevamente a la aplicación desde el dominio configurado en el proxy inverso, se observará que:

Los usuarios ya no se pierden tras los reinicios
No aparece el aviso de recreación de la base de datos
La interfaz muestra el nombre y las imágenes personalizadas

Con este paso, FileBrowser Quantum pasa de ser una instalación de pruebas a un servicio mucho más estable, seguro y reutilizable, manteniendo una arquitectura sencilla basada en Docker Compose.

Paso 12 · Actualizaciones de versión de la imagen Filebrowser Quantum

Filebrowser Quantum es un proyecto en constante desarrollo, con actualizaciones frecuentes. Durante la elaboración de este tutorial, se publicaron nuevas versiones de la imagen Docker, y la propia aplicación lo indicó en pantalla mediante un mensaje. Es importante tener en cuenta que eliminar el contenedor y volver a crearlo no garantiza que se descargue la versión más reciente de la imagen.

Al tratarse de un proyecto joven y en continua evolución, es recomendable actualizar periódicamente la imagen a la versión estable más reciente disponible.

En Docker, las imágenes se descargan mediante el comando docker pull. Si una imagen ya existe en local con la misma etiqueta, Docker no comprueba automáticamente si dicha etiqueta apunta a una versión más reciente en Docker Hub.

Las etiquetas genéricas como latest o stable no representan una versión fija de la imagen, sino un puntero que puede cambiar con el tiempo. Por este motivo, Docker no descarga automáticamente las actualizaciones asociadas a estas etiquetas, siendo necesario forzar explícitamente la comprobación de cambios.

La forma más recomendable y segura de actualizar la imagen consiste en forzar su descarga antes de recrear el contenedor. Ambos pasos pueden unificarse en un único comando, ya que Docker Compose detecta automáticamente los cambios y recrea el contenedor si es necesario:

sudo docker compose pull && sudo docker compose up -d

De este modo, si la etiqueta stable apunta a una nueva versión de la imagen, esta se descargará y el contenedor se recreará utilizando la versión actualizada, manteniendo intactos los datos, los usuarios y las configuraciones almacenados en los volúmenes persistentes.

En resumen, todos los datos de configuración y los archivos almacenados se mantienen persistentes, mientras que el servicio se actualiza a una versión más reciente y mejorada.

Conclusiones finales de esta guía paso a paso

Si has seguido estos pasos hasta aquí, habrás desplegado en tu servidor —ya sea en local o en la nube— una potente aplicación de almacenamiento seguro de archivos, completamente basada en software libre. La arquitectura propuesta combina simplicidad, control y seguridad, utilizando Docker Compose y un proxy inverso para ofrecer acceso cifrado mediante HTTPS.

A partir de esta base, el proyecto puede evolucionar hacia escenarios más avanzados, incorporando nuevas funcionalidades o integraciones adicionales según las necesidades del entorno. La estructura modular empleada en este despliegue facilita este tipo de ampliaciones sin comprometer la estabilidad del servicio.

En definitiva, Filebrowser Quantum ofrece una alternativa autoalojada, flexible y totalmente controlada por el usuario, ideal tanto para entornos personales como profesionales.

Como complemento de esta guía, puedes consultar su continuación natural: Integración de OnlyOffice con Filebrowser Quantum , donde se explica cómo añadir la edición de documentos directamente desde el navegador.