Ir al contenido
Oleaflyv0.4.12

Ejecutar un servidor

Almacenamiento, copias de seguridad y límites

Todos los ajustes de Oleafly Server, almacenamiento de archivos en disco o en un bucket de S3, PDF compilados, funcionamiento detrás de un proxy, límites para clases en una misma red y para cada cuenta, registros, copias de seguridad, restauraciones y actualizaciones.

Esta página trata del funcionamiento diario de Oleafly Server. Para instalarlo, empieza con Ejecutar un servidor de colaboración.

El servidor lee sus ajustes de variables de entorno. Una variable definida pero vacía cuenta como no definida. Si falta un ajuste o está mal formado, el servidor no arranca, y su registro dice cuál.

VariableQué haceValor predeterminado
OLEAFLY_PUBLIC_URLLa dirección HTTPS que las personas escriben en Oleafly. Puede incluir una ruta, como https://www.cs.example.edu/oleafly. Obligatorio. Los archivos de Compose y Coolify lo definen por ti.Ninguno
OLEAFLY_BINDLa dirección y el puerto en los que escucha el servidor.0.0.0.0:8080
OLEAFLY_DATA_DIRLa carpeta de la base de datos y los archivos almacenados./data
OLEAFLY_SERVER_NAMEEl nombre que ven las personas en Oleafly, como Smith Lab.Oleafly Server
OLEAFLY_SERVER_ICON_URLLa dirección HTTPS de una imagen cuadrada que se muestra junto al nombre.Ninguno
OLEAFLY_SETUP_CODETu propio código de configuración de un solo uso: al menos 12 letras o dígitos, con guiones o espacios si quieres. Sin él, el servidor genera uno.Generado
OLEAFLY_GITHUB_CLIENT_ID, OLEAFLY_GITHUB_CLIENT_SECRETActivan el inicio de sesión con GitHub.Desactivado
OLEAFLY_GITHUB_URLLa dirección de un GitHub Enterprise Server.https://github.com
OLEAFLY_GITHUB_API_URLLa dirección de la API de GitHub, si la tuya es poco habitual.https://api.github.com, o /api/v3 bajo OLEAFLY_GITHUB_URL
OLEAFLY_GITHUB_LABELEl texto del botón de inicio de sesión con GitHub.GitHub
OLEAFLY_OIDC_<NAME>_ISSUER, OLEAFLY_OIDC_<NAME>_CLIENT_ID, OLEAFLY_OIDC_<NAME>_CLIENT_SECRETActivan un proveedor de OpenID Connect llamado <NAME>.Desactivado
OLEAFLY_OIDC_<NAME>_LABELEl texto de su botón de inicio de sesión, como University login.<NAME>
OLEAFLY_OIDC_<NAME>_TRUST_EMAILTrata como verificada cada dirección de correo de este proveedor. Lee antes Direcciones de correo verificadas.false
OLEAFLY_SMTP_URL, OLEAFLY_MAIL_FROMCorreo. Lee Correo electrónico.Desactivado
OLEAFLY_OPEN_SIGNUPDa una cuenta de miembro a cualquiera que inicie sesión con uno de tus proveedores. Lee Registro abierto.false
OLEAFLY_WEBActiva el acceso desde el navegador. Lee Acceso desde el navegador.false
OLEAFLY_BLOB_STOREDónde se almacenan los archivos, como figuras y PDF. fs los guarda en OLEAFLY_DATA_DIR. Una dirección como s3://lab-bucket o s3://lab-bucket/oleafly los guarda en un bucket.fs
OLEAFLY_S3_ENDPOINTLa dirección de un almacén compatible con S3 distinto de Amazon S3, como MinIO o Cloudflare R2. Déjalo vacío para Amazon S3.Amazon S3
OLEAFLY_S3_REGIONLa región del bucket.us-east-1
OLEAFLY_S3_ACCESS_KEY_ID, OLEAFLY_S3_SECRET_ACCESS_KEYLa clave que usa el servidor para el bucket. Obligatorias con una dirección s3://.Ninguna
OLEAFLY_MAX_PROJECT_MBEl proyecto más grande que acepta el servidor, en megabytes.200
OLEAFLY_MAX_FILE_MBEl archivo individual más grande, en megabytes.50
OLEAFLY_MAX_MEMBERS_PER_PROJECTEl máximo de personas en un proyecto.20
OLEAFLY_ACCOUNT_STORAGE_MBEl máximo que pueden almacenar los proyectos de los que es propietaria una cuenta, en megabytes. Lee Límites por cuenta.Sin límite, o 100 con el registro abierto
OLEAFLY_MAX_PROJECTS_PER_ACCOUNTEl máximo de proyectos compartidos de los que puede ser propietaria una cuenta.Sin límite, o 50 con el registro abierto
OLEAFLY_UPLOADS_PER_HOURCuántas subidas de archivos e instantáneas puede hacer una cuenta en una hora.Sin límite, o 300 con el registro abierto
OLEAFLY_SIGN_IN_BURSTCuántas solicitudes de inicio de sesión puede hacer una dirección de red en una ráfaga. Un inicio de sesión necesita unas seis, así que el valor predeterminado cubre a 50 personas en una misma dirección que inician sesión a la vez.300
OLEAFLY_SIGN_IN_PER_MINUTECuántas solicitudes de inicio de sesión recupera cada minuto una dirección de red después de la ráfaga.120
OLEAFLY_EMAIL_LINKS_PER_IPCuántos correos de inicio de sesión envía el servidor a personas de una misma dirección de red en 15 minutos.100
OLEAFLY_EMAIL_LINKS_PER_ADDRESSCuántos correos de inicio de sesión puede recibir una dirección de correo en 15 minutos. No puede ser mayor que OLEAFLY_EMAIL_LINKS_PER_IP.3
OLEAFLY_DEVICE_CODES_PER_IPCuántos códigos de inicio de sesión pueden pedir en 10 minutos las personas de una misma dirección de red.100
OLEAFLY_SNAPSHOT_MEMORY_MBCuánta memoria, en megabytes, puede usar el servidor para generar instantáneas de proyectos.La mitad del límite de memoria del contenedor, o 1024 sin límite
OLEAFLY_BEHIND_PROXYToma la dirección de cada persona de la cabecera X-Forwarded-For que añade tu proxy. Los archivos de Compose, Coolify y Render lo activan.false
OLEAFLY_PROXY_HOPSPor cuántos proxies pasa cada solicitud antes de llegar al servidor. Necesita OLEAFLY_BEHIND_PROXY=true.1
OLEAFLY_LOG_LEVELCuánto registra el servidor: error, warn, info, debug o trace. Las bibliotecas que usa el servidor solo registran advertencias salvo que elijas debug o trace.info
OLEAFLY_SECURITY_LOG_DAYSCuántos días se conservan las entradas del registro de seguridad, las entradas de los registros de acceso a proyectos y las invitaciones de invitados respondidas o caducadas.365
OLEAFLY_ARCHIVE_DAYSCuántos días se conserva un proyecto después de que su propietario deja de compartirlo.30
OLEAFLY_POLL_HOLD_SECONDSCuánto tiempo mantiene abierta el servidor una solicitud de sondeo largo cuando no hay ediciones esperando, de 1 a 40 segundos. Manténlo unos segundos por debajo del tiempo de inactividad de cualquier proxy delante del servidor.25

En el archivo .env de Compose, pon un valor entre comillas simples si contiene $ o #. Los ajustes que guardan secretos también se pueden leer de archivos. Lee Mantener los secretos fuera de .env.

Por defecto el servidor lo guarda todo en OLEAFLY_DATA_DIR: la base de datos, los archivos que comparten las personas y las instantáneas de los proyectos. Las instantáneas son copias guardadas de cada proyecto que permiten a las personas unirse y ponerse al día rápidamente.

El servidor puede guardar los archivos y las instantáneas en Amazon S3 en su lugar, o en otro almacén con una API compatible con S3, como MinIO o Cloudflare R2. La base de datos se queda en OLEAFLY_DATA_DIR en ambos casos, así que el servidor sigue necesitando su carpeta de datos.

  1. Crea un bucket y bloquea el acceso público a él.

  2. Crea una clave que pueda leer, escribir y eliminar objetos en ese bucket y nada más. En Amazon S3 eso significa s3:GetObject, s3:PutObject y s3:DeleteObject sobre arn:aws:s3:::lab-bucket/*, o sobre arn:aws:s3:::lab-bucket/oleafly/* si usas una carpeta.

  3. Define las variables, por ejemplo en .env:

    Ventana del terminal
    OLEAFLY_BLOB_STORE=s3://lab-bucket/oleafly
    OLEAFLY_S3_REGION=eu-west-1
    OLEAFLY_S3_ACCESS_KEY_ID=your-access-key-id
    OLEAFLY_S3_SECRET_ACCESS_KEY=your-secret-access-key

Para un almacén distinto de Amazon S3, define también OLEAFLY_S3_ENDPOINT con su dirección, como https://minio.example.org:9000 o https://<account-id>.r2.cloudflarestorage.com, y define OLEAFLY_S3_REGION con la región que espera (auto para R2). http:// simple también funciona, pero úsalo solo cuando el almacén esté en la misma red privada que el servidor.

La parte posterior al nombre del bucket es una carpeta opcional. Cada archivo se nombra con su hash SHA-256 y está bajo los dos primeros caracteres de ese hash, así que un archivo cuyo hash empieza por 3f9a se almacena como oleafly/3f/3f9a.... Las instantáneas tienen su propia carpeta snapshots con una carpeta para cada proyecto. Cuando el servidor vuelve a leer un archivo o una instantánea, comprueba los bytes con el hash y rechaza el que no coincide. Sin bucket, la misma estructura está en la carpeta blobs dentro de OLEAFLY_DATA_DIR.

Si el bucket rechaza una solicitud, esa subida o descarga falla, y el registro del servidor muestra lo que dijo el bucket, como 403 Forbidden (AccessDenied). Un error del servidor, un tiempo de espera agotado o una conexión cortada es distinto: el servidor lo intenta hasta tres veces, con una breve pausa aleatoria entre intentos. Si no puede eliminar un objeto, lo anota y lo intenta de nuevo en cada pasada de mantenimiento, cada 6 horas, para que una caída no deje objetos huérfanos.

Cuando se comparte un proyecto, la aplicación del propietario sube su primera instantánea y la firma con la clave de ese dispositivo. A partir de entonces el servidor genera cada instantánea por sí mismo, a partir de la instantánea anterior y de los cambios que las personas enviaron desde entonces. Se genera una instantánea nueva cuando un proyecto acumula 1000 cambios desde la última. El servidor conserva siempre al menos los últimos 2000 cambios, así que un dispositivo que estuvo fuera poco tiempo se pone al día con ellos y no descarga el proyecto entero otra vez.

Generar una instantánea necesita unas diez veces el tamaño de la instantánea anterior más los cambios posteriores. El servidor solo inicia una generación que cabe en OLEAFLY_SNAPSHOT_MEMORY_MB, y las generaciones que se ejecutan a la vez comparten esa cantidad. Si una generación no cabe, el servidor la omite, registra cuánta memoria necesita y conserva todos los cambios del proyecto. Los dispositivos se ponen entonces al día con esos cambios unos pocos megabytes cada vez. Sube el ajuste y se generará la siguiente instantánea. El servidor no almacena una instantánea mayor que OLEAFLY_MAX_PROJECT_MB.

Cuando un propietario o un editor compila correctamente un proyecto compartido, su aplicación envía el PDF al servidor, con su archivo SyncTeX si lo hay. Envía como máximo uno por minuto para cada proyecto. El servidor conserva un PDF y un archivo SyncTeX por proyecto, con el nombre del archivo principal, quién lo compiló y cuándo. El acceso desde el navegador muestra este PDF a las personas del proyecto.

Cada subida reemplaza a la anterior, y el archivo antiguo se elimina cuando ya nada lo usa. Los archivos compilados se almacenan con los demás archivos, en disco o en el bucket, y se eliminan con su proyecto. Un archivo compilado puede llegar a OLEAFLY_MAX_FILE_MB. Cuenta para el almacenamiento de la cuenta del propietario, pero no para las subidas por hora.

Todos los miembros de un proyecto pueden leer sus archivos compilados. Solo los propietarios y los editores pueden reemplazarlos.

El servidor habla HTTP simple, así que algo delante de él se encarga de HTTPS: Caddy en la configuración de Compose, el proxy de Coolify o un servidor web que ya tengas, como el de tu universidad. Lo que esté delante tiene que:

  • aceptar solicitudes tan grandes como OLEAFLY_MAX_PROJECT_MB
  • añadir la dirección del cliente a X-Forwarded-For

También debería dejar pasar las actualizaciones a WebSocket hacia /ws y mantener esas conexiones abiertas al menos una hora. La edición en tiempo real las usa cuando puede. Con el acceso desde el navegador activado, también tiene que dejarlas pasar hacia /web/ws, porque la aplicación para el navegador no tiene ninguna alternativa más lenta.

Ejecuta el servidor donde solo el proxy pueda llegar a él. En la misma máquina, define OLEAFLY_BIND=127.0.0.1:8080. Después define OLEAFLY_BEHIND_PROXY=true.

Algunas redes bloquean las conexiones WebSocket, a menudo una red universitaria o de empresa con un proxy de filtrado. La edición en tiempo real sigue funcionando allí, pero más despacio. Cuando fallan dos intentos de WebSocket seguidos mientras el servidor sigue respondiendo por HTTPS, Oleafly pasa al sondeo largo por HTTP. Envía las ediciones a /api/v1/projects/<project>/frames y espera las de otras personas en /api/v1/projects/<project>/poll, manteniendo cada solicitud abierta hasta OLEAFLY_POLL_HOLD_SECONDS. Todas las ediciones siguen llegando. Oleafly vuelve a probar un WebSocket cada minuto y regresa a él en cuanto se conecta uno.

Probar la conexión en Oleafly y Pruebas de conexión en la consola de administración avisan cuando esto ocurre: “Las ediciones en tiempo real van por una vía más lenta porque esta red bloquea la habitual. Aun así llegan.”

Si gestionas el proxy delante del servidor, deja pasar las actualizaciones a WebSocket de todos modos. El sondeo largo funciona, pero cada lote de ediciones cuesta una solicitud extra y algo más de retraso.

Algunos proxies cierran una solicitud que permanece en silencio menos de 30 segundos, nginx con un proxy_read_timeout corto, por ejemplo. Responden a las solicitudes de sondeo largo con un error 502 o 504, y las ediciones llegan tarde. Define OLEAFLY_POLL_HOLD_SECONDS unos segundos por debajo de ese tiempo de espera, como 8 para un tiempo de espera de 10 segundos.

El servidor anota la dirección de un cliente en dos lugares: el registro de seguridad y los límites de la frecuencia con la que una dirección puede iniciar sesión o abrir una conexión en tiempo real.

Sin el ajuste, el servidor usa la dirección de lo que se conectó a él. Detrás de un proxy eso es siempre el proxy, así que todos comparten un solo límite y el registro de seguridad muestra solo la dirección del proxy.

Con OLEAFLY_BEHIND_PROXY=true, el servidor lee la cabecera X-Forwarded-For y usa la última dirección que contiene, que es la que añadió tu proxy. Si falta la cabecera o no contiene ninguna dirección válida, el servidor recurre a la dirección de conexión. No cambia nada más. El servidor ignora X-Forwarded-Proto, X-Forwarded-Host y Forwarded, y construye todas las direcciones que entrega a partir de OLEAFLY_PUBLIC_URL.

Actívalo solo cuando todas las solicitudes pasen por tu proxy. Si las personas también pueden llegar directamente al servidor, cualquiera puede enviar un X-Forwarded-For inventado, poner cualquier dirección en el registro de seguridad y saltarse el límite de inicios de sesión.

Con dos proxies seguidos, por ejemplo Cloudflare delante del proxy de Coolify, define OLEAFLY_PROXY_HOPS=2. El servidor toma entonces la segunda dirección empezando por el final. Cuenta solo los proxies por los que pasa cada solicitud. Un Cloudflare Tunnel que lleva directamente al servidor cuenta como uno.

Para comprobar la cifra, inicia sesión desde tu propio ordenador y abre Registro de seguridad en la consola de administración. La entrada más reciente debería mostrar tu dirección pública, la que informa un sitio como ifconfig.me. Si muestra una dirección privada o de Cloudflare, sube OLEAFLY_PROXY_HOPS en uno.

Caddy deja pasar las conexiones WebSocket y X-Forwarded-For sin ajustes adicionales, y obtiene el certificado por sí mismo. Poner HTTPS delante incluye el Caddyfile completo.

Primero obtén un certificado para el dominio, por ejemplo con certbot. Después guarda esto como /etc/nginx/conf.d/oleafly.conf y ejecuta sudo nginx -t && sudo systemctl reload nginx:

map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
server_name collab.example.org;
ssl_certificate /etc/letsencrypt/live/collab.example.org/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/collab.example.org/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_read_timeout 1h;
proxy_send_timeout 1h;
client_max_body_size 200m;
}
}

client_max_body_size coincide con el valor predeterminado de OLEAFLY_MAX_PROJECT_MB, que es 200. Si subes uno, sube el otro.

Necesitas Apache 2.4.47 o posterior, que incluyen Debian 12 y Ubuntu 22.04 y posteriores. Activa los módulos:

Ventana del terminal
sudo a2enmod proxy proxy_http ssl

Guarda esto como /etc/apache2/sites-available/oleafly.conf y ejecuta sudo a2ensite oleafly && sudo systemctl reload apache2:

<VirtualHost *:443>
ServerName collab.example.org
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/collab.example.org/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/collab.example.org/privkey.pem
ProxyPreserveHost On
ProxyPass / http://127.0.0.1:8080/ upgrade=websocket timeout=3600
ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>

upgrade=websocket deja pasar las conexiones WebSocket y timeout=3600 las mantiene abiertas una hora. Apache añade por sí mismo la dirección del cliente a X-Forwarded-For.

Si el servidor está bajo una ruta, incluye la ruta en OLEAFLY_PUBLIC_URL, por ejemplo https://www.cs.example.edu/oleafly, y en las direcciones de callback que registres en los proveedores de inicio de sesión. El servidor responde tanto con esa ruta como sin ella, así que tu proxy puede pasarla o quitarla. Con nginx, usa location /oleafly/ { con las mismas líneas dentro, y deja proxy_pass http://127.0.0.1:8080; sin ruta para que nginx pase la ruta.

Una clase entera suele iniciar sesión desde una misma dirección de red, como el NAT de una universidad. Los valores predeterminados están pensados para eso:

  • Inicios de sesión: una dirección recibe una ráfaga de 300 solicitudes de inicio de sesión y luego dos por segundo. Un inicio de sesión necesita unas seis, así que 50 personas pueden iniciar sesión a la vez. Cámbialos con OLEAFLY_SIGN_IN_BURST y OLEAFLY_SIGN_IN_PER_MINUTE.
  • Enlaces de correo: 100 a una misma dirección en 15 minutos, y 3 a una misma dirección de correo. Cámbialos con OLEAFLY_EMAIL_LINKS_PER_IP y OLEAFLY_EMAIL_LINKS_PER_ADDRESS.
  • Códigos de inicio de sesión: 100 códigos, y 10 códigos incorrectos, desde una misma dirección en 10 minutos. Cámbialo con OLEAFLY_DEVICE_CODES_PER_IP.
  • Las conexiones en tiempo real tienen su propio límite, más amplio, para que una clase entera detrás de una misma dirección pueda reconectarse a la vez tras un reinicio. Solo lo consumen las conexiones que no logran demostrar su sesión: una ráfaga de 300 y luego diez por segundo. Una conexión que demuestra su sesión cuenta en cambio contra su propio dispositivo, que puede reconectarse 60 veces en una ráfaga y luego una vez por segundo.

Todas las direcciones IPv6 de una misma red /64 cuentan como una sola dirección. Estos límites solo funcionan por persona cuando el servidor ve la dirección real de cada una, así que configura bien tu proxy.

El servidor hace ping a cada conexión en tiempo real cada 30 segundos. Cierra una conexión que deja esos ping sin respuesta durante 90 segundos, y una que deja de leer lo que envía el servidor.

Los límites de proyecto se aplican a todos: OLEAFLY_MAX_PROJECT_MB para un proyecto entero (200 MB por defecto), OLEAFLY_MAX_FILE_MB para un archivo (50 MB) y OLEAFLY_MAX_MEMBERS_PER_PROJECT para las personas de un proyecto (20). El Resumen de la consola de administración muestra los límites actuales.

Hay tres límites que se aplican a cada cuenta. Están desactivados hasta que los defines, salvo que el registro abierto esté activado, que los activa con estos valores predeterminados:

LímiteAjusteCon el registro abierto
Almacenamiento de los proyectos de los que es propietaria una cuentaOLEAFLY_ACCOUNT_STORAGE_MB100 MB
Proyectos compartidos de los que es propietaria una cuentaOLEAFLY_MAX_PROJECTS_PER_ACCOUNT50
Subidas que hace una cuenta en una horaOLEAFLY_UPLOADS_PER_HOUR300

Un valor que defines siempre tiene prioridad sobre el predeterminado. Cada uno tiene que ser un número entero de al menos 1.

  • Almacenamiento suma los archivos y el historial de cambios de todos los proyectos de los que es propietaria la cuenta, incluidos los archivados, y sus PDF compilados. Las instantáneas no cuentan. Un archivo que cualquiera añade a un proyecto cuenta para el propietario del proyecto. Cuando la cuenta del propietario está llena, el servidor rechaza archivos nuevos y PDF compilados para sus proyectos, y no puede compartir otro proyecto. El archivo se queda en el ordenador de la persona que lo añadió. El texto que escriben las personas se sigue sincronizando.
  • Proyectos compartidos cuenta los proyectos que comparte la cuenta, incluidos los que aún se están subiendo. Los proyectos archivados no cuentan, así que dejar de compartir uno libera espacio.
  • Subidas cuenta cada subida de archivos e instantáneas en un periodo de una hora. Los PDF compilados no cuentan. Oleafly vuelve a enviar más tarde, por sí solo, un archivo rechazado.

El Resumen de la consola de administración no muestra estos límites. Con el registro abierto activado, el registro del servidor los nombra cada vez que arranca.

  • El registro del servidor es lo que muestran docker compose logs oleafly-server, los Logs de Coolify o journalctl -u oleafly-server. OLEAFLY_LOG_LEVEL define cuánto dice.
  • El registro de seguridad anota inicios de sesión e inicios de sesión rechazados, dispositivos, personas, roles, ajustes, proyectos e invitados, cada uno con la hora y la dirección IP. Los administradores y los mantenedores lo leen en Registro de seguridad en la consola de administración. Las entradas con más de OLEAFLY_SECURITY_LOG_DAYS días se eliminan.
  • Los registros de acceso a proyectos anotan quién abrió un proyecto, se unió a él o descargó una copia, con el nombre del dispositivo y la hora. El propietario de un proyecto activa uno, cuando Permitir registros de acceso a proyectos está activado, y solo ese propietario puede leerlo. Se aplica la misma retención.

Lo que necesita una copia de seguridad completa depende de dónde se almacenen los archivos:

  • Archivos en disco (OLEAFLY_BLOB_STORE=fs, el valor predeterminado): la base de datos, los archivos y las instantáneas están todos en la carpeta de datos. Haz una copia de toda la carpeta.
  • Archivos en un bucket: la carpeta de datos contiene la base de datos y el bucket contiene los archivos y las instantáneas. Una copia de la base de datos más el bucket es una copia de seguridad completa. Activa el control de versiones del bucket para poder recuperar un objeto eliminado por error.
Dónde guarda los datos el servidor y qué copiarCon los archivos en el disco, la opción predeterminada, la carpeta de datos contiene la base de datos y la carpeta blobs con los archivos y las instantáneas, así que copias toda la carpeta. Con los archivos en un bucket, la carpeta de datos contiene la base de datos y un bucket de S3 guarda los archivos y las instantáneas, así que copias la base de datos y el bucket.Archivos en el disco (predeterminado)Archivos en un bucketoleafly-serverCarpeta de datosBase de datos: cuentas, ajustes, registrosblobs: archivos e instantáneasCopia toda la carpetaoleafly-serverCarpeta de datosBase de datosBucket de S3Archivos einstantáneasCopia la base de datos y el bucketDónde guarda los datos el servidor y qué copiarCon los archivos en el disco, la opción predeterminada, la carpeta de datos contiene la base de datos y la carpeta blobs con los archivos y las instantáneas, así que copias toda la carpeta. Con los archivos en un bucket, la carpeta de datos contiene la base de datos y un bucket de S3 guarda los archivos y las instantáneas, así que copias la base de datos y el bucket.Archivos en el disco (predeterminado)Archivos en un bucketoleafly-serverCarpeta de datosBase de datos y blobs(archivos, instantáneas)Copia toda la carpetaoleafly-serverCarpeta de datosBase de datosBucket de S3Archivos einstantáneasCopia la base de datosy el bucket
Lo que necesita una copia de seguridad completa depende de dónde se guardan los archivos.

Haz copias con regularidad y mantén las copias en privado, ya que contienen todos los proyectos. Tus ajustes, como .env, no están en la carpeta de datos, así que guarda también una copia de ellos.

Con Docker, el servidor se detiene unos segundos mientras copias el volumen. Oleafly se reconecta solo. Ejecuta estos comandos en la carpeta del servidor, /opt/oleafly-server si usaste el instalador.

Ventana del terminal
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo docker run --rm -v oleafly-server_oleafly-data:/data:ro -v "$PWD":/backup debian:13.7-slim tar -C /data -czf /backup/oleafly-data-$(date +%F).tar.gz .
sudo docker compose start oleafly-server

Con systemd:

Ventana del terminal
sudo systemctl stop oleafly-server
sudo tar -C /var/lib/private/oleafly-server -czf /root/oleafly-data-$(date +%F).tar.gz .
sudo systemctl start oleafly-server

Copia el archivo comprimido a otra máquina.

En Coolify, el nombre del volumen empieza por el ID del recurso. Encuéntralo con docker volume ls --filter name=oleafly-data, úsalo en lugar de oleafly-server_oleafly-data, y detén e inicia el servidor desde el panel de Coolify en vez de con docker compose.

Una copia de seguridad que nunca has restaurado es solo una esperanza. Este simulacro arranca una segunda copia del servidor a partir de una copia de seguridad, deja en paz la que está en marcha y comprueba que ambos son el mismo servidor. Usa la fecha de tu propio archivo en lugar de 2026-10-11.

Ventana del terminal
cd /opt/oleafly-server
sudo docker volume create oleafly-restore-drill
sudo docker run --rm -v oleafly-restore-drill:/data -v "$PWD":/backup:ro debian:13.7-slim tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz
sudo docker run -d --name oleafly-restore-drill -v oleafly-restore-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"
sudo docker run --rm --network container:oleafly-restore-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-server
curl -fsS https://collab.example.org/.well-known/oleafly-server

El server_id de las dos respuestas debe coincidir. La copia del simulacro tiene un inicio de sesión de GitHub de relleno que no puede iniciar sesión a nadie, y ningún puerto abierto, así que nadie puede usarla. Elimínala cuando termines:

Ventana del terminal
sudo docker rm -f oleafly-restore-drill
sudo docker volume rm oleafly-restore-drill

Para restaurar de verdad con Docker Compose, detén el servidor, sustituye el contenido del volumen por el archivo comprimido y arráncalo de nuevo:

Ventana del terminal
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo docker run --rm -v oleafly-server_oleafly-data:/data -v "$PWD":/backup:ro debian:13.7-slim sh -c 'find /data -mindepth 1 -delete && tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz'
sudo docker compose start oleafly-server

Con systemd:

Ventana del terminal
sudo systemctl stop oleafly-server
sudo find /var/lib/private/oleafly-server -mindepth 1 -delete
sudo tar -C /var/lib/private/oleafly-server -xzf /root/oleafly-data-2026-10-11.tar.gz
sudo systemctl start oleafly-server

Un servidor restaurado no tiene los cambios que las personas hicieron después de la copia de seguridad. Cada aplicación lo detecta al reconectarse, tanto si se quedó abierta como si se abrió más tarde, y vuelve a enviar sus propios cambios que faltan. Nadie tiene que hacer nada para eso. Un cambio que se apoya en un cambio que falta de otra persona espera hasta que esa persona abra el proyecto, porque solo su aplicación puede enviar sus cambios. Pide a todos los que estaban editando cerca del momento del fallo que abran el proyecto una vez.

Un archivo comprimido solo contiene lo que había cuando lo hiciste. Litestream (se abre en una pestaña nueva) copia cada cambio de la base de datos del servidor a un bucket compatible con S3 aproximadamente un segundo después de que ocurra. El archivo de Compose lo incluye como servicio opcional.

Litestream copia solo la base de datos. Si los archivos están en un bucket, el bucket ya contiene archivos e instantáneas, así que la copia de Litestream y el bucket juntos pueden recuperar un disco perdido. Si los archivos están en disco, sigue haciendo también archivos comprimidos del volumen, porque Litestream no copia la carpeta blobs.

  1. Crea un bucket, o una carpeta dentro de uno, que solo use el Litestream de este servidor. No lo compartas con OLEAFLY_BLOB_STORE. Dale a Litestream una clave que pueda listar el bucket y leer, escribir y eliminar objetos en él.

  2. Añade los datos a .env:

    Ventana del terminal
    LITESTREAM_REPLICA_URL=s3://lab-backups/oleafly-server
    LITESTREAM_REGION=eu-west-1
    LITESTREAM_ACCESS_KEY_ID=your-access-key-id
    LITESTREAM_SECRET_ACCESS_KEY=your-secret-access-key
    COMPOSE_PROFILES=litestream

    Para un almacén distinto de Amazon S3, define también LITESTREAM_ENDPOINT con su dirección y LITESTREAM_REGION con la región que espera (auto para R2). COMPOSE_PROFILES hace que cada comando docker compose incluya Litestream.

  3. Arráncalo:

    Ventana del terminal
    sudo docker compose up -d
  4. Comprueba que copió la base de datos. Esto imprime una línea con snapshot complete:

    Ventana del terminal
    sudo docker compose logs litestream | grep 'snapshot complete'

Litestream hace una copia completa una vez al día y conserva una semana de copias y los cambios entre ellas. El calendario está en litestream.yml.

Este simulacro restaura la base de datos desde el bucket en un volumen temporal, arranca una segunda copia del servidor sobre él y comprueba que ambos son el mismo servidor. El servidor en marcha no se toca.

Ventana del terminal
cd /opt/oleafly-server
sudo docker run --rm -v oleafly-litestream-drill:/data "$(sudo docker compose images -q oleafly-server)" --version
sudo docker compose run --rm --no-deps -v oleafly-litestream-drill:/restore litestream restore -config /etc/litestream.yml -o /restore/oleafly-server.sqlite3 /data/oleafly-server.sqlite3
sudo docker run -d --name oleafly-litestream-drill -v oleafly-litestream-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"
sudo docker run --rm --network container:oleafly-litestream-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-server
curl -fsS https://collab.example.org/.well-known/oleafly-server

El primer comando crea el volumen temporal con el propietario que necesita el servidor. El server_id de las dos últimas respuestas debe coincidir. Elimina la copia cuando termines:

Ventana del terminal
sudo docker rm -f oleafly-litestream-drill
sudo docker volume rm oleafly-litestream-drill

Cuando el archivo de la base de datos está dañado o ha desaparecido, pero el resto de la carpeta de datos está bien, detén el servidor y Litestream, elimina lo que quede de la base de datos, restáurala y arranca de nuevo:

Ventana del terminal
cd /opt/oleafly-server
sudo docker compose stop oleafly-server litestream
sudo docker run --rm -v oleafly-server_oleafly-data:/data debian:13.7-slim rm -rf /data/oleafly-server.sqlite3 /data/oleafly-server.sqlite3-wal /data/oleafly-server.sqlite3-shm /data/.oleafly-server.sqlite3-litestream
sudo docker compose run --rm --no-deps litestream restore -config /etc/litestream.yml /data/oleafly-server.sqlite3
sudo docker compose up -d

Tras perder un disco con archivos en un bucket, ejecuta los comandos anteriores en el volumen nuevo y vacío y mantén los mismos ajustes de bucket en .env. Todos los proyectos vuelven con sus archivos e instantáneas.

Tras perder un disco con archivos en disco, restaura tu archivo comprimido más reciente y déjalo así. No pongas una base de datos más reciente de Litestream encima de un archivo comprimido más antiguo. La base de datos apuntaría a archivos e instantáneas que el archivo comprimido no tiene, y esos proyectos no se abrirían.

Haz primero una copia de seguridad. El servidor actualiza su base de datos la primera vez que arranca una versión nueva, así que volver a una versión anterior significa restaurar la copia de seguridad que hiciste antes de actualizar.

  • Instalación con un comando: ejecuta curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update. Conserva .env, descarga los archivos y la imagen de la versión nueva y reinicia el servidor.
  • Docker Compose a mano: descarga los archivos de la versión nueva en la carpeta del servidor como en Docker Compose a mano, y luego ejecuta sudo docker compose up -d.
  • Coolify: selecciona Redeploy. Con la imagen publicada, eso descarga la versión más reciente bajo la etiqueta de la imagen.
  • Render: abre el servicio e inicia un despliegue manual, que vuelve a descargar la imagen.
  • Railway: vuelve a desplegar el servicio desde su menú. Railway también puede actualizar por sí mismo una imagen del registro de GitHub.
  • systemd: instala la versión nueva como en Descargar el servidor, y luego ejecuta sudo systemctl restart oleafly-server.

Oleafly comprueba la versión del servidor cada vez que se conecta. Si la aplicación y el servidor no pueden trabajar juntos, Oleafly dice cuál de los dos necesita una actualización.

Vista previa de la imagen

No se pudieron cargar las respuestas de la IA

Inténtalo de nuevo o busca en la documentación.