Pular para o conteúdo
Oleaflyv0.4.12

Executar um servidor

Todas as configurações do Oleafly Server, armazenamento de arquivos em disco ou em um bucket S3, PDFs compilados, execução atrás de um proxy, limites para turmas em uma mesma rede e para cada conta, registros, backups, restaurações e atualizações.

Esta página cobre a operação do Oleafly Server no dia a dia. Para instalá-lo, comece por Execute um servidor de colaboração.

O servidor lê as configurações dele em variáveis de ambiente. Uma variável definida, porém vazia, conta como não definida. Se uma configuração estiver faltando ou malformada, o servidor não inicia, e o log dele diz qual.

VariávelO que ela fazPadrão
OLEAFLY_PUBLIC_URLO endereço HTTPS que as pessoas digitam no Oleafly. Pode incluir um caminho, como https://www.cs.example.edu/oleafly. Obrigatória. Os arquivos do Compose e do Coolify a definem para você.Nenhum
OLEAFLY_BINDO endereço e a porta em que o servidor escuta.0.0.0.0:8080
OLEAFLY_DATA_DIRA pasta para o banco de dados e os arquivos armazenados./data
OLEAFLY_SERVER_NAMEO nome que as pessoas veem no Oleafly, como Smith Lab.Oleafly Server
OLEAFLY_SERVER_ICON_URLO endereço HTTPS de uma imagem quadrada exibida ao lado do nome.Nenhum
OLEAFLY_SETUP_CODEO seu próprio código de configuração de uso único: pelo menos 12 letras ou dígitos, com traços ou espaços se preferir. Sem ele, o servidor cria um.Gerado
OLEAFLY_GITHUB_CLIENT_ID, OLEAFLY_GITHUB_CLIENT_SECRETAtivam o login com o GitHub.Desativado
OLEAFLY_GITHUB_URLO endereço de um GitHub Enterprise Server.https://github.com
OLEAFLY_GITHUB_API_URLO endereço da API do GitHub, se o seu for incomum.https://api.github.com, ou /api/v3 sob OLEAFLY_GITHUB_URL
OLEAFLY_GITHUB_LABELO texto no botão de login com o GitHub.GitHub
OLEAFLY_OIDC_<NAME>_ISSUER, OLEAFLY_OIDC_<NAME>_CLIENT_ID, OLEAFLY_OIDC_<NAME>_CLIENT_SECRETAtivam um provedor OpenID Connect chamado <NAME>.Desativado
OLEAFLY_OIDC_<NAME>_LABELO texto no botão de login dele, como University login.<NAME>
OLEAFLY_OIDC_<NAME>_TRUST_EMAILTrata todo endereço de e-mail deste provedor como verificado. Leia primeiro Endereços de e-mail verificados.false
OLEAFLY_SMTP_URL, OLEAFLY_MAIL_FROME-mail. Leia E-mail.Desativado
OLEAFLY_OPEN_SIGNUPDá a qualquer pessoa que fizer login com um dos seus provedores uma conta como membro. Leia Cadastro aberto.false
OLEAFLY_WEBAtiva o acesso pelo navegador. Leia Acesso pelo navegador.false
OLEAFLY_BLOB_STOREOnde arquivos como figuras e PDFs são armazenados. fs os mantém em OLEAFLY_DATA_DIR. Um endereço como s3://lab-bucket ou s3://lab-bucket/oleafly os mantém em um bucket.fs
OLEAFLY_S3_ENDPOINTO endereço de um armazenamento compatível com S3 que não seja o Amazon S3, como MinIO ou Cloudflare R2. Deixe vazia para o Amazon S3.Amazon S3
OLEAFLY_S3_REGIONA região do bucket.us-east-1
OLEAFLY_S3_ACCESS_KEY_ID, OLEAFLY_S3_SECRET_ACCESS_KEYA chave que o servidor usa para o bucket. Obrigatória com um endereço s3://.Nenhum
OLEAFLY_MAX_PROJECT_MBO maior projeto que o servidor aceita, em megabytes.200
OLEAFLY_MAX_FILE_MBO maior arquivo único, em megabytes.50
OLEAFLY_MAX_MEMBERS_PER_PROJECTO máximo de pessoas em um projeto.20
OLEAFLY_ACCOUNT_STORAGE_MBO máximo que os projetos de que uma conta é proprietária podem armazenar, em megabytes. Leia Limites por conta.Sem limite, ou 100 com cadastro aberto
OLEAFLY_MAX_PROJECTS_PER_ACCOUNTO máximo de projetos compartilhados de que uma conta pode ser proprietária.Sem limite, ou 50 com cadastro aberto
OLEAFLY_UPLOADS_PER_HOURQuantos envios de arquivos e de snapshots uma conta pode fazer em uma hora.Sem limite, ou 300 com cadastro aberto
OLEAFLY_SIGN_IN_BURSTQuantas requisições de login um endereço de rede pode fazer em uma rajada. Um login gasta cerca de seis, então o padrão cobre 50 pessoas em um endereço entrando de uma vez.300
OLEAFLY_SIGN_IN_PER_MINUTEQuantas requisições de login um endereço de rede recebe de volta por minuto depois da rajada.120
OLEAFLY_EMAIL_LINKS_PER_IPQuantos e-mails de login o servidor envia para pessoas em um endereço de rede em 15 minutos.100
OLEAFLY_EMAIL_LINKS_PER_ADDRESSQuantos e-mails de login um endereço de e-mail pode receber em 15 minutos. Não pode ser mais que OLEAFLY_EMAIL_LINKS_PER_IP.3
OLEAFLY_DEVICE_CODES_PER_IPQuantos códigos de login pessoas em um endereço de rede podem pedir em 10 minutos.100
OLEAFLY_SNAPSHOT_MEMORY_MBQuanta memória, em megabytes, o servidor pode usar para construir snapshots de projetos.Metade do limite de memória do contêiner, ou 1024 sem limite
OLEAFLY_BEHIND_PROXYPega o endereço de cada pessoa no cabeçalho X-Forwarded-For que o seu proxy adiciona. Os arquivos do Compose, do Coolify e do Render a ativam.false
OLEAFLY_PROXY_HOPSPor quantos proxies cada requisição passa antes de chegar ao servidor. Ela precisa de OLEAFLY_BEHIND_PROXY=true.1
OLEAFLY_LOG_LEVELQuanto o servidor registra: error, warn, info, debug ou trace. As bibliotecas que o servidor usa só registram avisos, a menos que você escolha debug ou trace.info
OLEAFLY_SECURITY_LOG_DAYSPor quantos dias manter entradas do registro de segurança, entradas dos registros de acesso a projetos e convites de convidados respondidos ou expirados.365
OLEAFLY_ARCHIVE_DAYSPor quantos dias manter um projeto depois que o proprietário para de compartilhá-lo.30
OLEAFLY_POLL_HOLD_SECONDSPor quanto tempo o servidor mantém aberta uma requisição de long-polling quando não há edições esperando, de 1 a 40 segundos. Mantenha-a alguns segundos abaixo do tempo limite de inatividade de qualquer proxy à frente do servidor.25

No arquivo .env do Compose, coloque um valor entre aspas simples se ele contiver $ ou #. Configurações que guardam segredos também podem ser lidas de arquivos. Leia Mantenha os segredos fora do .env.

Por padrão, o servidor guarda tudo em OLEAFLY_DATA_DIR: o banco de dados, os arquivos que as pessoas compartilham e os snapshots dos projetos. Snapshots são cópias salvas de cada projeto que permitem que as pessoas entrem e se atualizem rapidamente.

O servidor pode, em vez disso, manter arquivos e snapshots no Amazon S3, ou em outro armazenamento com uma API compatível com S3, como MinIO ou Cloudflare R2. De qualquer forma, o banco de dados fica em OLEAFLY_DATA_DIR, então o servidor ainda precisa da pasta de dados dele.

  1. Crie um bucket e bloqueie o acesso público a ele.

  2. Crie uma chave que possa ler, gravar e excluir objetos naquele bucket e nada mais. No Amazon S3, isso significa s3:GetObject, s3:PutObject e s3:DeleteObject em arn:aws:s3:::lab-bucket/*, ou em arn:aws:s3:::lab-bucket/oleafly/* se você usar uma pasta.

  3. Defina as variáveis, por exemplo em .env:

    Janela do 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 um armazenamento que não seja o Amazon S3, defina também OLEAFLY_S3_ENDPOINT com o endereço dele, como https://minio.example.org:9000 ou https://<account-id>.r2.cloudflarestorage.com, e defina OLEAFLY_S3_REGION com a região que ele espera (auto para R2). http:// puro também funciona, mas use-o somente quando o armazenamento estiver na mesma rede privada que o servidor.

A parte depois do nome do bucket é uma pasta opcional. Cada arquivo recebe o nome do hash SHA-256 dele e fica sob os dois primeiros caracteres desse hash, então um arquivo cujo hash começa com 3f9a é armazenado como oleafly/3f/3f9a.... Os snapshots têm a própria pasta snapshots, com uma pasta para cada projeto. Quando o servidor lê de volta um arquivo ou snapshot, ele confere os bytes com o hash e recusa um que não corresponda. Sem bucket, o mesmo layout fica na pasta blobs dentro de OLEAFLY_DATA_DIR.

Se o bucket recusar uma requisição, aquele envio ou download falha, e o log do servidor mostra o que o bucket disse, como 403 Forbidden (AccessDenied). Um erro do servidor, um tempo limite ou uma conexão derrubada é diferente: o servidor tenta até três vezes, com uma pausa curta e aleatória entre elas. Se ele não conseguir excluir um objeto, anota isso e tenta de novo em cada ciclo de manutenção, que roda a cada 6 horas, então uma queda não deixa objetos para trás.

Quando um projeto é compartilhado, o aplicativo do proprietário envia o primeiro snapshot dele e o assina com a chave daquele dispositivo. De ali em diante, o servidor constrói todos os snapshots sozinho, a partir do snapshot anterior e das mudanças que as pessoas enviaram desde então. Um novo snapshot é construído quando um projeto acumula 1.000 mudanças além do último. O servidor sempre guarda pelo menos as últimas 2.000 mudanças, então um dispositivo que ficou fora por um curto tempo se atualiza a partir delas e não baixa o projeto inteiro de novo.

Construir um snapshot precisa de cerca de dez vezes o tamanho do snapshot anterior mais as mudanças desde então. O servidor só inicia uma construção que caiba em OLEAFLY_SNAPSHOT_MEMORY_MB, e construções rodando ao mesmo tempo dividem esse valor. Se uma construção não couber, o servidor a pula, registra quanta memória ela precisa e guarda todas as mudanças do projeto. Os dispositivos então se atualizam a partir dessas mudanças, alguns megabytes por vez. Aumente a configuração e o próximo snapshot será construído. O servidor não armazena um snapshot maior que OLEAFLY_MAX_PROJECT_MB.

Quando um proprietário ou editor compila um projeto compartilhado com sucesso, o aplicativo dele envia o PDF ao servidor, com o arquivo SyncTeX quando houver um. Ele envia no máximo um por minuto para cada projeto. O servidor guarda um PDF e um arquivo SyncTeX por projeto, com o nome do arquivo principal, quem o compilou e quando. O acesso pelo navegador mostra esse PDF às pessoas do projeto.

Cada envio substitui o anterior, e o arquivo antigo é excluído quando nada mais o usa. Os arquivos compilados são armazenados com os outros arquivos, em disco ou no bucket, e são excluídos junto com o projeto deles. Um arquivo compilado pode ter até OLEAFLY_MAX_FILE_MB. Ele conta para o armazenamento da conta do proprietário, mas não para os envios por hora.

Todos os membros de um projeto podem ler os arquivos compilados dele. Só proprietários e editores podem substituí-los.

O servidor fala HTTP puro, então algo na frente dele cuida do HTTPS: o Caddy na configuração do Compose, o proxy do Coolify ou um servidor web que você já opera, como o da sua universidade. O que estiver na frente precisa:

  • aceitar requisições tão grandes quanto OLEAFLY_MAX_PROJECT_MB
  • adicionar o endereço do cliente ao X-Forwarded-For

Ele também deve encaminhar os upgrades de WebSocket para /ws e manter essas conexões abertas por pelo menos uma hora. A edição ao vivo as usa quando pode. Com o acesso pelo navegador ativado, ele também precisa encaminhá-los para /web/ws, porque o aplicativo para navegador não tem uma alternativa mais lenta.

Execute o servidor onde só o proxy consiga alcançá-lo. Na mesma máquina, defina OLEAFLY_BIND=127.0.0.1:8080. Depois defina OLEAFLY_BEHIND_PROXY=true.

Algumas redes bloqueiam conexões WebSocket, muitas vezes uma rede de universidade ou empresa com um proxy de filtragem. A edição ao vivo ainda funciona ali, mais devagar. Quando duas tentativas de WebSocket seguidas falham enquanto o servidor ainda responde por HTTPS, o Oleafly muda para o long-polling por HTTP. Ele envia edições para /api/v1/projects/<project>/frames e espera as edições das outras pessoas em /api/v1/projects/<project>/poll, mantendo cada requisição aberta por até OLEAFLY_POLL_HOLD_SECONDS. Toda edição ainda chega. O Oleafly tenta um WebSocket de novo a cada minuto e volta para ele assim que um conecta.

Testar conexão no Oleafly e Testes de conexão no console de administração dizem quando isso acontece: “As edições ao vivo seguem por um caminho mais lento porque esta rede bloqueia o caminho de sempre. Elas continuam chegando.”

Se você opera o proxy à frente do servidor, encaminhe os upgrades de WebSocket mesmo assim. O long-polling funciona, mas cada lote de edições custa uma requisição extra e um pouco mais de atraso.

Alguns proxies fecham uma requisição que fica quieta por menos de 30 segundos, o nginx com um proxy_read_timeout curto, por exemplo. Eles respondem requisições de long-polling com um erro 502 ou 504, e as edições chegam atrasadas. Defina OLEAFLY_POLL_HOLD_SECONDS alguns segundos abaixo desse tempo limite, como 8 para um tempo limite de 10 segundos.

O servidor anota um endereço de cliente em dois lugares: o registro de segurança e os limites de quantas vezes um endereço pode iniciar um login ou abrir uma conexão ao vivo.

Sem a configuração, o servidor usa o endereço do que quer que tenha se conectado a ele. Atrás de um proxy, isso é sempre o proxy, então todo mundo divide um limite e o registro de segurança mostra só o endereço do proxy.

Com OLEAFLY_BEHIND_PROXY=true, o servidor lê o cabeçalho X-Forwarded-For e usa o último endereço nele, que é o que o seu proxy adicionou. Se o cabeçalho estiver faltando ou não tiver um endereço válido, o servidor volta ao endereço de quem conectou. Nada mais muda. O servidor ignora X-Forwarded-Proto, X-Forwarded-Host e Forwarded, e constrói todo endereço que entrega a partir de OLEAFLY_PUBLIC_URL.

Ative-a somente quando toda requisição passar pelo seu proxy. Se as pessoas também conseguirem alcançar o servidor diretamente, qualquer pessoa pode enviar um X-Forwarded-For inventado, colocar qualquer endereço no registro de segurança e contornar o limite de logins.

Com dois proxies em sequência, por exemplo o Cloudflare na frente do proxy do Coolify, defina OLEAFLY_PROXY_HOPS=2. O servidor então pega o segundo endereço a partir do fim. Conte só os proxies pelos quais toda requisição passa. Um Cloudflare Tunnel que leva direto ao servidor conta como um.

Para conferir o número, faça login do seu próprio computador e abra Registro de segurança no console de administração. A entrada mais recente deve mostrar o seu endereço público, o que um site como ifconfig.me informa. Se mostrar um endereço privado ou do Cloudflare, aumente OLEAFLY_PROXY_HOPS em um.

O Caddy encaminha conexões WebSocket e X-Forwarded-For sem configurações extras e obtém o certificado sozinho. Coloque o HTTPS na frente tem o Caddyfile completo.

Primeiro obtenha um certificado para o domínio, por exemplo com o certbot. Depois salve isto como /etc/nginx/conf.d/oleafly.conf e execute 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;
}
}

O client_max_body_size corresponde ao OLEAFLY_MAX_PROJECT_MB padrão de 200. Se você aumentar um, aumente o outro.

Você precisa do Apache 2.4.47 ou mais novo, que o Debian 12 e o Ubuntu 22.04 e posteriores têm. Ative os módulos:

Janela do terminal
sudo a2enmod proxy proxy_http ssl

Salve isto como /etc/apache2/sites-available/oleafly.conf, depois execute 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>

O upgrade=websocket encaminha conexões WebSocket e o timeout=3600 as mantém abertas por uma hora. O Apache adiciona sozinho o endereço do cliente ao X-Forwarded-For.

Se o servidor fica sob um caminho, inclua o caminho em OLEAFLY_PUBLIC_URL, por exemplo https://www.cs.example.edu/oleafly, e nos endereços de callback que você registra nos provedores de login. O servidor responde com e sem esse caminho, então o seu proxy pode repassá-lo ou removê-lo. Com nginx, use location /oleafly/ { com as mesmas linhas dentro e mantenha proxy_pass http://127.0.0.1:8080; sem caminho, para o nginx repassar o caminho.

Uma turma inteira costuma fazer login de um só endereço de rede, como o NAT de uma universidade. Os padrões são definidos para isso:

  • Logins: um endereço recebe uma rajada de 300 requisições de login e depois duas por segundo. Um login gasta cerca de seis, então 50 pessoas podem entrar de uma vez. Mude isso com OLEAFLY_SIGN_IN_BURST e OLEAFLY_SIGN_IN_PER_MINUTE.
  • Links de e-mail: 100 para um endereço em 15 minutos e 3 para um endereço de e-mail. Mude isso com OLEAFLY_EMAIL_LINKS_PER_IP e OLEAFLY_EMAIL_LINKS_PER_ADDRESS.
  • Códigos de login: 100 códigos e 10 códigos errados, de um endereço em 10 minutos. Mude isso com OLEAFLY_DEVICE_CODES_PER_IP.
  • As conexões ao vivo têm um limite próprio, maior, para uma turma inteira atrás de um endereço poder se reconectar de uma vez depois de uma reinicialização. Só as conexões que não conseguem comprovar a sessão delas o consomem: uma rajada de 300 e depois dez por segundo. Uma conexão que comprova a sessão conta para o próprio dispositivo dela, que pode se reconectar 60 vezes em uma rajada e depois uma vez por segundo.

Todos os endereços IPv6 de uma mesma rede /64 contam como um endereço. Esses limites só funcionam por pessoa quando o servidor vê o endereço real de cada uma, então configure o seu proxy corretamente.

O servidor faz ping em cada conexão ao vivo a cada 30 segundos. Ele fecha uma conexão que deixa esses pings sem resposta por 90 segundos e uma que para de ler o que o servidor envia.

Os limites de projeto valem para todos: OLEAFLY_MAX_PROJECT_MB para um projeto inteiro (200 MB por padrão), OLEAFLY_MAX_FILE_MB para um arquivo (50 MB) e OLEAFLY_MAX_MEMBERS_PER_PROJECT para pessoas em um projeto (20). A Visão geral do console de administração mostra os limites atuais.

Três limites valem para cada conta. Eles ficam desativados até você defini-los, a menos que o cadastro aberto esteja ativado, o que os ativa com estes padrões:

LimiteConfiguraçãoCom cadastro aberto
Armazenamento dos projetos de que uma conta é proprietáriaOLEAFLY_ACCOUNT_STORAGE_MB100 MB
Projetos compartilhados de que uma conta é proprietáriaOLEAFLY_MAX_PROJECTS_PER_ACCOUNT50
Envios que uma conta faz em uma horaOLEAFLY_UPLOADS_PER_HOUR300

Um valor que você define sempre vale mais que o padrão. Cada um precisa ser um número inteiro de pelo menos 1.

  • Armazenamento soma os arquivos e o histórico de alterações de todos os projetos de que a conta é proprietária, incluindo os arquivados, e os PDFs compilados deles. Os snapshots não contam. Um arquivo que qualquer pessoa adiciona a um projeto conta para o proprietário do projeto. Quando a conta do proprietário fica cheia, o servidor recusa novos arquivos e PDFs compilados para os projetos dele, e ele não pode compartilhar outro projeto. O arquivo fica no computador de quem o adicionou. O texto que as pessoas digitam continua sincronizando.
  • Projetos compartilhados conta os projetos que a conta compartilha, incluindo os que ainda estão sendo enviados. Os projetos arquivados não contam, então parar de compartilhar um deles libera espaço.
  • Envios conta cada envio de arquivo e de snapshot em uma janela de uma hora. Os PDFs compilados não contam. O Oleafly envia de novo um arquivo recusado mais tarde, sozinho.

A Visão geral do console de administração não mostra esses limites. Com o cadastro aberto ativado, o log do servidor os informa toda vez que ele inicia.

  • O log do servidor é o que docker compose logs oleafly-server, o Logs do Coolify ou journalctl -u oleafly-server mostram. OLEAFLY_LOG_LEVEL define quanto ele diz.
  • O registro de segurança registra logins e logins recusados, dispositivos, pessoas, funções, configurações, projetos e convidados, cada um com a hora e o endereço IP. Administradores e mantenedores o leem em Registro de segurança no console de administração. Entradas mais antigas que OLEAFLY_SECURITY_LOG_DAYS dias são excluídas.
  • Os registros de acesso a projetos registram quem abriu um projeto, entrou nele ou baixou uma cópia, com o nome do dispositivo e a hora. O proprietário de um projeto ativa um quando Permitir registros de acesso a projetos está ativado, e só esse proprietário pode lê-lo. A mesma retenção se aplica.

Do que um backup completo precisa depende de onde os arquivos são armazenados:

  • Arquivos em disco (OLEAFLY_BLOB_STORE=fs, o padrão): o banco de dados, os arquivos e os snapshots estão todos na pasta de dados. Faça backup da pasta inteira.
  • Arquivos em um bucket: a pasta de dados guarda o banco de dados e o bucket guarda arquivos e snapshots. Uma cópia do banco de dados mais o bucket é um backup completo. Ative o versionamento do bucket para que um objeto excluído por engano possa ser recuperado.
Onde o servidor guarda os dados e o que incluir no backupCom os arquivos no disco, o padrão, a pasta de dados contém o banco de dados e a pasta blobs com arquivos e snapshots, então você faz backup da pasta inteira. Com os arquivos em um bucket, a pasta de dados contém o banco de dados e um bucket S3 guarda arquivos e snapshots, então você faz backup do banco de dados e do bucket.Arquivos no disco (padrão)Arquivos em um bucketoleafly-serverPasta de dadosBanco de dados: contas, configurações, logsblobs: arquivos e snapshotsFaça backup da pasta inteiraoleafly-serverPasta de dadosBanco de dadosBucket S3Arquivos esnapshotsFaça backup do banco de dados e do bucketOnde o servidor guarda os dados e o que incluir no backupCom os arquivos no disco, o padrão, a pasta de dados contém o banco de dados e a pasta blobs com arquivos e snapshots, então você faz backup da pasta inteira. Com os arquivos em um bucket, a pasta de dados contém o banco de dados e um bucket S3 guarda arquivos e snapshots, então você faz backup do banco de dados e do bucket.Arquivos no disco (padrão)Arquivos em um bucketoleafly-serverPasta de dadosBanco de dados e blobs(arquivos, snapshots)Faça backup da pasta inteiraoleafly-serverPasta de dadosBanco de dadosBucket S3Arquivos esnapshotsFaça backup do banco de dadose do bucket
O que um backup completo exige depende de onde os arquivos ficam.

Faça backups regularmente e mantenha as cópias privadas, já que elas contêm todos os projetos. As suas configurações, como .env, não estão na pasta de dados, então guarde também uma cópia delas.

Com Docker, o servidor para por alguns segundos enquanto você copia o volume. O Oleafly se reconecta sozinho. Execute estes comandos na pasta do servidor, /opt/oleafly-server se você usou o instalador.

Janela do 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

Com systemd:

Janela do 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

Copie o arquivo compactado para outra máquina.

No Coolify, o nome do volume começa com o ID do recurso. Encontre-o com docker volume ls --filter name=oleafly-data, use-o no lugar de oleafly-server_oleafly-data, e pare e inicie o servidor pelo painel do Coolify em vez de com docker compose.

Um backup que você nunca restaurou é só uma esperança. Este simulado inicia uma segunda cópia do servidor a partir de um backup, deixa o que está rodando em paz e confere que os dois são o mesmo servidor. Use a data do seu próprio arquivo compactado no lugar de 2026-10-11.

Janela do 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

O server_id nas duas respostas deve corresponder. A cópia do simulado tem um login de GitHub de exemplo que não faz login de ninguém e nenhuma porta aberta, então ninguém pode usá-la. Remova-a quando terminar:

Janela do terminal
sudo docker rm -f oleafly-restore-drill
sudo docker volume rm oleafly-restore-drill

Para restaurar de verdade com Docker Compose, pare o servidor, substitua o conteúdo do volume pelo arquivo compactado e inicie-o de novo:

Janela do 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

Com systemd:

Janela do 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

Um servidor restaurado fica sem as mudanças que as pessoas fizeram depois do backup. Cada aplicativo percebe quando se reconecta, tenha ficado aberto ou sido aberto depois, e envia de novo as mudanças dele que faltam. Ninguém precisa fazer nada para isso. Uma mudança que se apoia em uma mudança ausente de outra pessoa espera até essa pessoa abrir o projeto, porque só o aplicativo dela pode enviar as mudanças dela. Peça a todos que estavam editando perto da hora da falha para abrir o projeto uma vez.

Um arquivo compactado guarda só o que estava lá quando você o criou. O Litestream (abre em uma nova guia) copia cada mudança no banco de dados do servidor para um bucket compatível com S3 cerca de um segundo depois de ela acontecer. O arquivo do Compose o inclui como um serviço opcional.

O Litestream copia só o banco de dados. Se os arquivos estão em um bucket, o bucket já guarda arquivos e snapshots, então a cópia do Litestream e o bucket juntos recuperam um disco perdido. Se os arquivos estão em disco, continue criando arquivos compactados do volume também, porque o Litestream não copia a pasta blobs.

  1. Crie um bucket, ou uma pasta em um, que só o Litestream deste servidor use. Não o compartilhe com OLEAFLY_BLOB_STORE. Dê ao Litestream uma chave que possa listar o bucket e ler, gravar e excluir objetos nele.

  2. Adicione os detalhes ao .env:

    Janela do 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 um armazenamento que não seja o Amazon S3, defina também LITESTREAM_ENDPOINT com o endereço dele e LITESTREAM_REGION com a região que ele espera (auto para R2). O COMPOSE_PROFILES faz todo comando docker compose incluir o Litestream.

  3. Inicie-o:

    Janela do terminal
    sudo docker compose up -d
  4. Confira que ele copiou o banco de dados. Isto imprime uma linha com snapshot complete:

    Janela do terminal
    sudo docker compose logs litestream | grep 'snapshot complete'

O Litestream faz uma cópia completa uma vez por dia e guarda uma semana de cópias e as mudanças entre elas. O cronograma está em litestream.yml.

Este simulado restaura o banco de dados do bucket em um volume temporário, inicia uma segunda cópia do servidor nele e confere que os dois são o mesmo servidor. O servidor em execução não é tocado.

Janela do 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

O primeiro comando cria o volume temporário com o dono que o servidor precisa. O server_id nas duas últimas respostas deve corresponder. Remova a cópia quando terminar:

Janela do terminal
sudo docker rm -f oleafly-litestream-drill
sudo docker volume rm oleafly-litestream-drill

Restauração do banco de dados a partir do Litestream

Seção intitulada “Restauração do banco de dados a partir do Litestream”

Quando o arquivo do banco de dados está danificado ou sumiu, mas o resto da pasta de dados está bem, pare o servidor e o Litestream, remova o que sobrou do banco de dados, restaure-o e inicie de novo:

Janela do 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

Depois de um disco perdido com arquivos em um bucket, execute os comandos acima no novo volume, vazio, e mantenha as mesmas configurações de bucket no .env. Cada projeto volta com os arquivos e snapshots dele.

Depois de um disco perdido com arquivos em disco, restaure o seu arquivo compactado mais recente e pare por aí. Não coloque um banco de dados mais novo do Litestream por cima de um arquivo compactado mais antigo. O banco de dados apontaria para arquivos e snapshots que o arquivo compactado não tem, e esses projetos não abririam.

Faça backup primeiro. O servidor atualiza o banco de dados dele na primeira vez que uma versão nova inicia, então voltar a uma versão mais antiga significa restaurar o backup que você fez antes de atualizar.

  • Instalação com um comando: execute curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update. Ele mantém o .env, obtém os arquivos e a imagem da nova versão e reinicia o servidor.
  • Docker Compose à mão: baixe os arquivos da nova versão para a pasta do servidor como em Docker Compose à mão e execute sudo docker compose up -d.
  • Coolify: selecione Redeploy. Com a imagem publicada, isso baixa a versão mais nova sob a tag da imagem.
  • Render: abra o serviço e inicie um deploy manual, que baixa a imagem de novo.
  • Railway: faça o deploy do serviço de novo pelo menu dele. O Railway também pode atualizar sozinho uma imagem do registro do GitHub.
  • systemd: instale a nova versão como em Baixar o servidor e execute sudo systemctl restart oleafly-server.

O Oleafly confere a versão do servidor toda vez que se conecta. Se o aplicativo e o servidor não conseguirem trabalhar juntos, o Oleafly diz qual precisa de atualização.

Visualização da imagem

Não foi possível carregar as respostas da IA

Tente de novo ou pesquise na documentação.