# 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](/docs/collaboration/server/).

## 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](/docs/collaboration/server-access/#verified-email-addresses). | `false` |
| `OLEAFLY_SMTP_URL`, `OLEAFLY_MAIL_FROM` | E-mail. Leia [E-mail](/docs/collaboration/server-access/#email). | Desativado |
| `OLEAFLY_OPEN_SIGNUP` | Dá a qualquer pessoa que fizer login com um dos seus provedores uma conta como membro. Leia [Cadastro aberto](/docs/collaboration/server-access/#open-sign-up). | `false` |
| `OLEAFLY_WEB` | Ativa o acesso pelo navegador. Leia [Acesso pelo navegador](/docs/collaboration/server-access/#browser-access). | `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](#limits-per-account). | 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](/docs/collaboration/server/#keep-secrets-out-of-env).

## 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

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`:

   ```sh
   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.

### 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

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](/docs/collaboration/server-access/#browser-access) 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](#limits-per-account) 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

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

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

O servidor anota um endereço de cliente em dois lugares: o registro de segurança e os [limites](#limits-for-a-class-on-one-network) 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.

### Caddy

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](/docs/collaboration/server/#put-https-in-front) tem o `Caddyfile` completo.

### nginx

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`:

```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.

### Apache

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:

```sh
sudo a2enmod proxy proxy_http ssl
```

Salve isto como `/etc/apache2/sites-available/oleafly.conf`, depois execute `sudo a2ensite oleafly && sudo systemctl reload apache2`:

```apache
<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 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

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](#what-oleafly_behind_proxy-changes) 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

Três limites valem para cada conta. Eles ficam desativados até você defini-los, a menos que o [cadastro aberto](/docs/collaboration/server-access/#open-sign-up) 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

- **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.

## 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.

```sh
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:

```sh
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`.

### 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`.

```sh
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:

```sh
sudo docker rm -f oleafly-restore-drill
sudo docker volume rm oleafly-restore-drill
```

### 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:

```sh
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:

```sh
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.

### Cópias contínuas com Litestream

Um arquivo compactado guarda só o que estava lá quando você o criou. O [Litestream](https://litestream.io) 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`:

   ```sh
   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:

   ```sh
   sudo docker compose up -d
   ```

4. Confira que ele copiou o banco de dados. Isto imprime uma linha com `snapshot complete`:

   ```sh
   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

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.

```sh
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:

```sh
sudo docker rm -f oleafly-litestream-drill
sudo docker volume rm oleafly-litestream-drill
```

#### 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:

```sh
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](#restore) 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

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](/docs/collaboration/server/#docker-compose-by-hand) 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](/docs/collaboration/server/#download-the-server) 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.
