Executar um servidor
Armazenamento, backups e limites
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.
Configurações
Seção intitulada “Configurações”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ável | O que ela faz | Padrão |
|---|---|---|
OLEAFLY_PUBLIC_URL | O 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_BIND | O endereço e a porta em que o servidor escuta. | 0.0.0.0:8080 |
OLEAFLY_DATA_DIR | A pasta para o banco de dados e os arquivos armazenados. | /data |
OLEAFLY_SERVER_NAME | O nome que as pessoas veem no Oleafly, como Smith Lab. | Oleafly Server |
OLEAFLY_SERVER_ICON_URL | O endereço HTTPS de uma imagem quadrada exibida ao lado do nome. | Nenhum |
OLEAFLY_SETUP_CODE | O 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_SECRET | Ativam o login com o GitHub. | Desativado |
OLEAFLY_GITHUB_URL | O endereço de um GitHub Enterprise Server. | https://github.com |
OLEAFLY_GITHUB_API_URL | O endereço da API do GitHub, se o seu for incomum. | https://api.github.com, ou /api/v3 sob OLEAFLY_GITHUB_URL |
OLEAFLY_GITHUB_LABEL | O texto no botão de login com o GitHub. | GitHub |
OLEAFLY_OIDC_<NAME>_ISSUER, OLEAFLY_OIDC_<NAME>_CLIENT_ID, OLEAFLY_OIDC_<NAME>_CLIENT_SECRET | Ativam um provedor OpenID Connect chamado <NAME>. | Desativado |
OLEAFLY_OIDC_<NAME>_LABEL | O texto no botão de login dele, como University login. | <NAME> |
OLEAFLY_OIDC_<NAME>_TRUST_EMAIL | Trata todo endereço de e-mail deste provedor como verificado. Leia primeiro Endereços de e-mail verificados. | false |
OLEAFLY_SMTP_URL, OLEAFLY_MAIL_FROM | E-mail. Leia E-mail. | Desativado |
OLEAFLY_OPEN_SIGNUP | Dá a qualquer pessoa que fizer login com um dos seus provedores uma conta como membro. Leia Cadastro aberto. | false |
OLEAFLY_WEB | Ativa o acesso pelo navegador. Leia Acesso pelo navegador. | false |
OLEAFLY_BLOB_STORE | Onde 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_ENDPOINT | O 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_REGION | A região do bucket. | us-east-1 |
OLEAFLY_S3_ACCESS_KEY_ID, OLEAFLY_S3_SECRET_ACCESS_KEY | A chave que o servidor usa para o bucket. Obrigatória com um endereço s3://. | Nenhum |
OLEAFLY_MAX_PROJECT_MB | O maior projeto que o servidor aceita, em megabytes. | 200 |
OLEAFLY_MAX_FILE_MB | O maior arquivo único, em megabytes. | 50 |
OLEAFLY_MAX_MEMBERS_PER_PROJECT | O máximo de pessoas em um projeto. | 20 |
OLEAFLY_ACCOUNT_STORAGE_MB | O 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_ACCOUNT | O máximo de projetos compartilhados de que uma conta pode ser proprietária. | Sem limite, ou 50 com cadastro aberto |
OLEAFLY_UPLOADS_PER_HOUR | Quantos envios de arquivos e de snapshots uma conta pode fazer em uma hora. | Sem limite, ou 300 com cadastro aberto |
OLEAFLY_SIGN_IN_BURST | Quantas 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_MINUTE | Quantas requisições de login um endereço de rede recebe de volta por minuto depois da rajada. | 120 |
OLEAFLY_EMAIL_LINKS_PER_IP | Quantos e-mails de login o servidor envia para pessoas em um endereço de rede em 15 minutos. | 100 |
OLEAFLY_EMAIL_LINKS_PER_ADDRESS | Quantos 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_IP | Quantos códigos de login pessoas em um endereço de rede podem pedir em 10 minutos. | 100 |
OLEAFLY_SNAPSHOT_MEMORY_MB | Quanta 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_PROXY | Pega 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_HOPS | Por quantos proxies cada requisição passa antes de chegar ao servidor. Ela precisa de OLEAFLY_BEHIND_PROXY=true. | 1 |
OLEAFLY_LOG_LEVEL | Quanto 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_DAYS | Por 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_DAYS | Por quantos dias manter um projeto depois que o proprietário para de compartilhá-lo. | 30 |
OLEAFLY_POLL_HOLD_SECONDS | Por 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.
Armazenamento
Seção intitulada “Armazenamento”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.
Arquivos em um bucket
Seção intitulada “Arquivos em um bucket”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.
-
Crie um bucket e bloqueie o acesso público a ele.
-
Crie uma chave que possa ler, gravar e excluir objetos naquele bucket e nada mais. No Amazon S3, isso significa
s3:GetObject,s3:PutObjectes3:DeleteObjectemarn:aws:s3:::lab-bucket/*, ou emarn:aws:s3:::lab-bucket/oleafly/*se você usar uma pasta. -
Defina as variáveis, por exemplo em
.env:Janela do 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 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.
Snapshots e memória
Seção intitulada “Snapshots e memória”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.
PDFs compilados
Seção intitulada “PDFs compilados”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.
Atrás de um proxy reverso
Seção intitulada “Atrás de um proxy reverso”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.
Quando as conexões WebSocket são bloqueadas
Seção intitulada “Quando as conexões WebSocket são bloqueadas”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 que a OLEAFLY_BEHIND_PROXY muda
Seção intitulada “O que a OLEAFLY_BEHIND_PROXY muda”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:
sudo a2enmod proxy proxy_http sslSalve 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.
Sob um caminho
Seção intitulada “Sob um caminho”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.
Limites para uma turma em uma mesma rede
Seção intitulada “Limites para uma turma em uma mesma rede”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_BURSTeOLEAFLY_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_IPeOLEAFLY_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.
Limites por conta
Seção intitulada “Limites por conta”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:
| Limite | Configuração | Com cadastro aberto |
|---|---|---|
| Armazenamento dos projetos de que uma conta é proprietária | OLEAFLY_ACCOUNT_STORAGE_MB | 100 MB |
| Projetos compartilhados de que uma conta é proprietária | OLEAFLY_MAX_PROJECTS_PER_ACCOUNT | 50 |
| Envios que uma conta faz em uma hora | OLEAFLY_UPLOADS_PER_HOUR | 300 |
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.
Registros
Seção intitulada “Registros”- O log do servidor é o que
docker compose logs oleafly-server, o Logs do Coolify oujournalctl -u oleafly-servermostram.OLEAFLY_LOG_LEVELdefine 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_DAYSdias 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.
Backups
Seção intitulada “Backups”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.
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.
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-serverCom 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-serverCopie 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.
Simulado de restauração
Seção intitulada “Simulado de restauração”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.
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-serverO 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:
sudo docker rm -f oleafly-restore-drillsudo docker volume rm oleafly-restore-drillRestauração
Seção intitulada “Restauração”Para restaurar de verdade com Docker Compose, pare o servidor, substitua o conteúdo do volume pelo arquivo compactado e inicie-o de novo:
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-serverCom 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-serverUm 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.
Cópias contínuas com Litestream
Seção intitulada “Cópias contínuas com Litestream”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.
-
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. -
Adicione os detalhes ao
.env:Janela do 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 um armazenamento que não seja o Amazon S3, defina também
LITESTREAM_ENDPOINTcom o endereço dele eLITESTREAM_REGIONcom a região que ele espera (autopara R2). OCOMPOSE_PROFILESfaz todo comandodocker composeincluir o Litestream. -
Inicie-o:
Janela do terminal sudo docker compose up -d -
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.
Simulado de restauração do Litestream
Seção intitulada “Simulado de restauração do Litestream”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.
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-serverO 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:
sudo docker rm -f oleafly-litestream-drillsudo docker volume rm oleafly-litestream-drillRestauraçã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:
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 -dDepois 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.
Atualização
Seção intitulada “Atualização”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.