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.
Ajustes
Sección titulada «Ajustes»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.
| Variable | Qué hace | Valor predeterminado |
|---|---|---|
OLEAFLY_PUBLIC_URL | La 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_BIND | La dirección y el puerto en los que escucha el servidor. | 0.0.0.0:8080 |
OLEAFLY_DATA_DIR | La carpeta de la base de datos y los archivos almacenados. | /data |
OLEAFLY_SERVER_NAME | El nombre que ven las personas en Oleafly, como Smith Lab. | Oleafly Server |
OLEAFLY_SERVER_ICON_URL | La dirección HTTPS de una imagen cuadrada que se muestra junto al nombre. | Ninguno |
OLEAFLY_SETUP_CODE | Tu 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_SECRET | Activan el inicio de sesión con GitHub. | Desactivado |
OLEAFLY_GITHUB_URL | La dirección de un GitHub Enterprise Server. | https://github.com |
OLEAFLY_GITHUB_API_URL | La 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_LABEL | El 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_SECRET | Activan un proveedor de OpenID Connect llamado <NAME>. | Desactivado |
OLEAFLY_OIDC_<NAME>_LABEL | El texto de su botón de inicio de sesión, como University login. | <NAME> |
OLEAFLY_OIDC_<NAME>_TRUST_EMAIL | Trata como verificada cada dirección de correo de este proveedor. Lee antes Direcciones de correo verificadas. | false |
OLEAFLY_SMTP_URL, OLEAFLY_MAIL_FROM | Correo. Lee Correo electrónico. | Desactivado |
OLEAFLY_OPEN_SIGNUP | Da una cuenta de miembro a cualquiera que inicie sesión con uno de tus proveedores. Lee Registro abierto. | false |
OLEAFLY_WEB | Activa el acceso desde el navegador. Lee Acceso desde el navegador. | false |
OLEAFLY_BLOB_STORE | Dó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_ENDPOINT | La 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_REGION | La región del bucket. | us-east-1 |
OLEAFLY_S3_ACCESS_KEY_ID, OLEAFLY_S3_SECRET_ACCESS_KEY | La clave que usa el servidor para el bucket. Obligatorias con una dirección s3://. | Ninguna |
OLEAFLY_MAX_PROJECT_MB | El proyecto más grande que acepta el servidor, en megabytes. | 200 |
OLEAFLY_MAX_FILE_MB | El archivo individual más grande, en megabytes. | 50 |
OLEAFLY_MAX_MEMBERS_PER_PROJECT | El máximo de personas en un proyecto. | 20 |
OLEAFLY_ACCOUNT_STORAGE_MB | El 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_ACCOUNT | El 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_HOUR | Cuá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_BURST | Cuá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_MINUTE | Cuá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_IP | Cuá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_ADDRESS | Cuá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_IP | Cuá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_MB | Cuá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_PROXY | Toma 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_HOPS | Por cuántos proxies pasa cada solicitud antes de llegar al servidor. Necesita OLEAFLY_BEHIND_PROXY=true. | 1 |
OLEAFLY_LOG_LEVEL | Cuá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_DAYS | Cuá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_DAYS | Cuántos días se conserva un proyecto después de que su propietario deja de compartirlo. | 30 |
OLEAFLY_POLL_HOLD_SECONDS | Cuá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.
Almacenamiento
Sección titulada «Almacenamiento»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.
Archivos en un bucket
Sección titulada «Archivos en un bucket»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.
-
Crea un bucket y bloquea el acceso público a él.
-
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:PutObjectys3:DeleteObjectsobrearn:aws:s3:::lab-bucket/*, o sobrearn:aws:s3:::lab-bucket/oleafly/*si usas una carpeta. -
Define las variables, por ejemplo en
.env:Ventana del terminal OLEAFLY_BLOB_STORE=s3://lab-bucket/oleaflyOLEAFLY_S3_REGION=eu-west-1OLEAFLY_S3_ACCESS_KEY_ID=your-access-key-idOLEAFLY_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.
Instantáneas y memoria
Sección titulada «Instantáneas y memoria»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.
PDF compilados
Sección titulada «PDF compilados»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.
Detrás de un proxy inverso
Sección titulada «Detrás de un proxy inverso»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.
Cuando se bloquean las conexiones WebSocket
Sección titulada «Cuando se bloquean las conexiones WebSocket»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.
Qué cambia OLEAFLY_BEHIND_PROXY
Sección titulada «Qué cambia OLEAFLY_BEHIND_PROXY»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:
sudo a2enmod proxy proxy_http sslGuarda 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.
Bajo una ruta
Sección titulada «Bajo una ruta»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.
Límites para una clase en una misma red
Sección titulada «Límites para una clase en una misma red»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_BURSTyOLEAFLY_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_IPyOLEAFLY_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.
Límites por cuenta
Sección titulada «Límites por cuenta»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ímite | Ajuste | Con el registro abierto |
|---|---|---|
| Almacenamiento de los proyectos de los que es propietaria una cuenta | OLEAFLY_ACCOUNT_STORAGE_MB | 100 MB |
| Proyectos compartidos de los que es propietaria una cuenta | OLEAFLY_MAX_PROJECTS_PER_ACCOUNT | 50 |
| Subidas que hace una cuenta en una hora | OLEAFLY_UPLOADS_PER_HOUR | 300 |
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.
Registros
Sección titulada «Registros»- El registro del servidor es lo que muestran
docker compose logs oleafly-server, los Logs de Coolify ojournalctl -u oleafly-server.OLEAFLY_LOG_LEVELdefine 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_DAYSdí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.
Copias de seguridad
Sección titulada «Copias de seguridad»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.
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.
cd /opt/oleafly-serversudo docker compose stop oleafly-serversudo 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-serverCon systemd:
sudo systemctl stop oleafly-serversudo tar -C /var/lib/private/oleafly-server -czf /root/oleafly-data-$(date +%F).tar.gz .sudo systemctl start oleafly-serverCopia 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.
Simulacro de restauración
Sección titulada «Simulacro de restauración»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.
cd /opt/oleafly-serversudo docker volume create oleafly-restore-drillsudo 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.gzsudo 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-servercurl -fsS https://collab.example.org/.well-known/oleafly-serverEl 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:
sudo docker rm -f oleafly-restore-drillsudo docker volume rm oleafly-restore-drillRestaurar
Sección titulada «Restaurar»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:
cd /opt/oleafly-serversudo docker compose stop oleafly-serversudo 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-serverCon systemd:
sudo systemctl stop oleafly-serversudo find /var/lib/private/oleafly-server -mindepth 1 -deletesudo tar -C /var/lib/private/oleafly-server -xzf /root/oleafly-data-2026-10-11.tar.gzsudo systemctl start oleafly-serverUn 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.
Copias continuas con Litestream
Sección titulada «Copias continuas con Litestream»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.
-
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. -
Añade los datos a
.env:Ventana del terminal LITESTREAM_REPLICA_URL=s3://lab-backups/oleafly-serverLITESTREAM_REGION=eu-west-1LITESTREAM_ACCESS_KEY_ID=your-access-key-idLITESTREAM_SECRET_ACCESS_KEY=your-secret-access-keyCOMPOSE_PROFILES=litestreamPara un almacén distinto de Amazon S3, define también
LITESTREAM_ENDPOINTcon su dirección yLITESTREAM_REGIONcon la región que espera (autopara R2).COMPOSE_PROFILEShace que cada comandodocker composeincluya Litestream. -
Arráncalo:
Ventana del terminal sudo docker compose up -d -
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.
Simulacro de restauración con Litestream
Sección titulada «Simulacro de restauración con Litestream»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.
cd /opt/oleafly-serversudo docker run --rm -v oleafly-litestream-drill:/data "$(sudo docker compose images -q oleafly-server)" --versionsudo 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.sqlite3sudo 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-servercurl -fsS https://collab.example.org/.well-known/oleafly-serverEl 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:
sudo docker rm -f oleafly-litestream-drillsudo docker volume rm oleafly-litestream-drillRestaurar la base de datos desde Litestream
Sección titulada «Restaurar la base de datos desde Litestream»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:
cd /opt/oleafly-serversudo docker compose stop oleafly-server litestreamsudo 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-litestreamsudo docker compose run --rm --no-deps litestream restore -config /etc/litestream.yml /data/oleafly-server.sqlite3sudo docker compose up -dTras 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.
Actualizar
Sección titulada «Actualizar»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.