# Execute um servidor de colaboração

O que o Oleafly Server guarda, o que ele precisa e como instalá-lo com um comando, ou executá-lo com Docker Compose, Coolify, Render, Railway ou um serviço Linux comum, e então se tornar o primeiro administrador dele.

O Oleafly Server é o servidor de colaboração por trás da colaboração em tempo real. O seu laboratório, departamento ou instituição o executa nas próprias máquinas ou na própria conta de nuvem. As pessoas o adicionam no Oleafly e fazem login com uma conta que já têm, como o GitHub ou um login de universidade. Quando alguém compartilha um projeto no servidor, as pessoas que ela adiciona recebem uma cópia completa que permanece sincronizada enquanto editam. Com o [acesso pelo navegador](/docs/collaboration/server-access/#browser-access) ativado, elas também podem abri-lo em um navegador da web.

Este guia é para a pessoa que executa o servidor para um laboratório, um curso ou um grupo de coautores. Você deve estar confortável com um terminal. Algumas instalações também pedem que você edite um arquivo de configuração. Não é preciso escrever código.

Para a sua revisão de segurança, leia [Segurança do servidor](/security/). Ela cobre a auto-hospedagem, o login, as chaves de dispositivo, as alterações assinadas, o registro de segurança e os registros de acesso, e a imagem de contêiner com a lista de materiais de software dela.

## O que o servidor guarda

O servidor guarda tudo em uma pasta de dados, definida por `OLEAFLY_DATA_DIR`:

- **Contas**: o nome de exibição de cada membro, o endereço do avatar, os endereços de e-mail verificados e o ID de usuário e o login dele no provedor de login. O servidor nunca vê nem armazena uma senha.
- **Dispositivos**: cada computador que fez login, com o nome, o sistema operacional, a chave pública e quando foi visto pela última vez. Os tokens de login são armazenados apenas como hashes.
- **O registro de segurança**: logins e logins recusados, dispositivos adicionados e com a sessão encerrada, alterações em membros, funções e configurações, projetos compartilhados, arquivados e restaurados, alterações em quem pode abrir um projeto e convites de convidados. Cada entrada tem a hora e o endereço IP.
- **Configurações do servidor** que os administradores mudam no Oleafly.
- **Registros de acesso a projetos**, para projetos cujo proprietário ativa um: quem abriu o projeto, entrou nele ou baixou uma cópia, com o nome do dispositivo e a hora. Somente o proprietário do projeto pode lê-lo.
- **Convites de convidados**: o endereço de e-mail convidado, o projeto, a função e quem o enviou.
- **Projetos compartilhados**: todos os arquivos e o histórico completo de alterações, com os comentários, as sugestões, o chat e os nomes de versões que pertencem a eles.
- **PDFs compilados**: para cada projeto compartilhado, o PDF mais recente, e o arquivo SyncTeX dele, que o aplicativo de um proprietário ou editor enviou depois de uma compilação bem-sucedida, com quem o compilou e quando.

As entradas do registro de segurança e dos registros de acesso, e os convites de convidados respondidos ou expirados, são excluídos após `OLEAFLY_SECURITY_LOG_DAYS` dias, 365 por padrão. Arquivos que um projeto não usa mais, como a cópia antiga de uma figura substituída, são excluídos 30 dias depois da última vez que o projeto os usou. Cada PDF compilado substitui o anterior. Quando um proprietário para de compartilhar um projeto, o servidor o mantém como somente leitura por `OLEAFLY_ARCHIVE_DAYS` dias, 30 por padrão, e depois o exclui. Nesse período, somente o proprietário e quaisquer administradores do projeto podem baixá-lo.

### Quem pode ler os projetos

Os projetos não são criptografados no servidor. Qualquer pessoa que possa ler a pasta de dados, o disco da máquina ou os seus backups pode ler todos os projetos armazenados ali. Isso inclui quem executa a máquina e a empresa que a hospeda.

Dentro do Oleafly, as regras são mais rígidas. Nenhuma função do servidor, administrador incluso, pode abrir um projeto, a menos que o proprietário do projeto tenha adicionado a pessoa. Se um projeto precisa ficar longe das pessoas que executam um servidor, execute um servidor separado para ele.

O computador de cada membro também mantém uma cópia completa de cada projeto compartilhado com ele. Peça aos membros que ativem a criptografia de disco, como FileVault no macOS, BitLocker no Windows ou LUKS no Linux.

## O que você precisa

- **Uma máquina que fica ligada.** Qualquer máquina Linux serve, ou uma conta em um serviço de hospedagem como Render ou Railway. Uma máquina virtual pequena é suficiente para começar. Acompanhe a memória e o disco dela conforme os projetos crescem. O servidor executa em x86-64 e ARM.
- **Um nome de domínio** para o servidor, como `collab.example.org`, com um registro DNS apontando para a máquina. Render e Railway dão um endereço se você não tiver um. Se a máquina não tem endereço público, leia [Sem endereço público](#without-a-public-address).
- **Uma forma de as pessoas fazerem login**: pelo menos um provedor de login, como um aplicativo OAuth do GitHub ou o login da sua instituição. O servidor não inicia sem um. Uma conta de e-mail da qual o servidor possa enviar é opcional. Com ela, um administrador também pode deixar as pessoas fazerem login com um link por e-mail. Leia [Login e acesso](/docs/collaboration/server-access/).

Cada lançamento é publicado como uma imagem de contêiner, `ghcr.io/oleafly/oleafly-server`. O instalador e os arquivos Compose dele estão na [página de lançamentos do Oleafly Server](https://github.com/Oleafly/oleafly-server/releases). O servidor como um programa Linux único está na [página de lançamentos do Oleafly](https://github.com/Oleafly/Oleafly/releases).

## Escolha como executá-lo

| Opção | Quando usar |
| --- | --- |
| [Um comando](#install-with-one-command) | Uma máquina Linux que você cuida. O instalador configura o Docker, o Caddy e o HTTPS, e faz algumas perguntas. Comece aqui se estiver em dúvida. |
| [Docker Compose à mão](#docker-compose-by-hand) | Você prefere colocar e editar cada arquivo você mesmo. |
| [Coolify](#coolify) | Você já administra um servidor Coolify. |
| [Render](#render) ou [Railway](#railway) | Você prefere pagar um serviço de hospedagem a cuidar de uma máquina. |
| [Linux sem Docker](#linux-without-docker) | Uma máquina virtual de universidade onde você não pode usar o Docker. |

O servidor lê as configurações dele em variáveis de ambiente. [Armazenamento, backups e limites](/docs/collaboration/server-operations/#settings) lista todas elas.

## Instale com um comando

Em uma máquina Linux que você mesmo cuida, o instalador configura tudo e pergunta apenas o que precisa saber.

Antes de executá-lo, verifique se:

- A máquina executa Linux em x86-64 ou ARM, como Ubuntu 24.04 ou Debian 13, e você pode usar `sudo` nela.
- Nada mais na máquina usa as portas 80 e 443. Abra as portas TCP 80 e 443 e a porta UDP 443 em qualquer firewall à frente dela.
- O registro DNS do seu domínio aponta para a máquina. Se ainda não aponta, a instalação mesmo assim termina, e o Caddy continua tentando obter um certificado até o registro entrar no lugar.
- Você tem os dados de pelo menos um [provedor de login](/docs/collaboration/server-access/#sign-in-providers), como o ID de cliente e o segredo de um aplicativo OAuth do GitHub. Para o GitHub, o endereço de retorno de chamada é `https://` e o seu domínio, seguidos de `/auth/callback/github`.

:::note[Durante o beta]
Instale a versão candidata, Oleafly Server 0.1.1-rc, para que o servidor corresponda ao Oleafly 0.4.7-rc:

```sh
curl -fsSL https://github.com/Oleafly/oleafly-server/releases/download/server-v0.1.1-rc/install.sh | sudo sh
```

O comando abaixo instala a 0.1.0, que é mais antiga. Se você executar a imagem de outra forma, como com Compose, Coolify, Render ou Railway, use `ghcr.io/oleafly/oleafly-server:0.1.1-rc`.
:::

Depois execute:

```sh
curl -fsSL https://oleafly.com/server/install.sh | sudo sh
```

O instalador:

1. Verifica a máquina e se as portas 80 e 443 estão livres.
2. Verifica se há Docker. Se estiver faltando, o instalador pergunta antes de instalá-lo com o script do próprio Docker.
3. Baixa os arquivos do lançamento mais recente dos [lançamentos do Oleafly Server](https://github.com/Oleafly/oleafly-server/releases) e verifica cada um contra o `SHA256SUMS` do lançamento. Se um arquivo não corresponder, ele para sem mudar nada.
4. Pergunta o seu domínio, o nome do servidor e como as pessoas fazem login. Ele também oferece configurar o e-mail e manter arquivos em um bucket S3. Ambos são opcionais.
5. Mostra um resumo e pergunta antes de mudar qualquer coisa. Então ele grava os arquivos dele em `/opt/oleafly-server`, com as suas configurações em `.env`, que só o root pode ler.
6. Inicia o servidor com o Caddy à frente, espera até o seu domínio responder por HTTPS e imprime o endereço e o código de configuração.

Depois [torne-se o primeiro administrador](#become-the-first-admin).

Você pode executar o instalador de novo a qualquer momento. Quando ele encontra um servidor em `/opt/oleafly-server`, mantém o `.env` como está, recoloca os outros arquivos e reinicia o servidor. Isso conserta a maioria das instalações quebradas.

Os seus dados ficam no volume do Docker `oleafly-server_oleafly-data`. Para instalar em um lugar diferente de `/opt/oleafly-server`, defina `OLEAFLY_DIR`, por exemplo `curl -fsSL https://oleafly.com/server/install.sh | sudo OLEAFLY_DIR=/srv/oleafly sh`, e use essa pasta nos comandos abaixo.

### Leia o instalador primeiro

Se a sua instituição não permite canalizar um script para um shell, baixe `install.sh` e `SHA256SUMS` do [lançamento mais recente](https://github.com/Oleafly/oleafly-server/releases/latest) para uma pasta. Verifique o script, leia-o e depois execute-o:

```sh
sha256sum --check --ignore-missing SHA256SUMS
sudo sh install.sh
```

### Instale sem perguntas

Para um script ou uma ferramenta de provisionamento, adicione `--yes` e passe as respostas como variáveis de ambiente. `OLEAFLY_INSTALL_DOCKER=yes` permite que o instalador adicione o Docker se estiver faltando.

```sh
curl -fsSL https://oleafly.com/server/install.sh | sudo \
  OLEAFLY_DOMAIN=collab.example.org \
  OLEAFLY_SERVER_NAME='Smith Lab' \
  OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId \
  OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret \
  OLEAFLY_INSTALL_DOCKER=yes \
  sh -s -- --yes
```

O instalador usa qualquer configuração que encontrar no ambiente sem perguntar, com ou sem `--yes`. `sudo sh /opt/oleafly-server/install.sh --help` lista todas, incluindo OpenID Connect, e-mail e S3. Valores digitados em uma linha de comando podem acabar no histórico do seu shell, então uma ferramenta de provisionamento deve passar segredos do próprio cofre de segredos dela.

### Status, atualizações e remoção

- **Status**: `sudo sh /opt/oleafly-server/install.sh status` mostra se o servidor está em execução e se o seu domínio responde por HTTPS com um certificado válido.
- **Atualização**: faça backup antes, como [Atualização](/docs/collaboration/server-operations/#updating) explica. Depois execute o comando abaixo. Ele baixa os arquivos e a imagem do lançamento mais recente, mantém o `.env`, reinicia o servidor e espera até ele responder. As pessoas conectadas se reconectam sozinhas. O instalador nunca move um servidor para um lançamento mais antigo.

  ```sh
  curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update
  ```

- **Desinstalação**: `sudo sh /opt/oleafly-server/install.sh uninstall` para e remove os contêineres. Os seus dados e o `.env` ficam, a menos que você digite `delete` quando ele perguntar. Excluí-los remove todos os projetos compartilhados no servidor, todas as contas e o registro de segurança. As pessoas mantêm as próprias cópias dos projetos nos computadores delas.

Se o instalador parar com um problema que você não consegue consertar, [relate-o](https://github.com/Oleafly/oleafly-server/issues/new/choose) com o que ele imprimiu.

## Docker Compose à mão

Esta configuração executa dois contêineres. `oleafly-server` é o servidor, e só os outros contêineres conseguem alcançá-lo. `caddy` obtém um certificado da Let's Encrypt, serve HTTPS nas portas 80 e 443 e repassa as requisições ao servidor, conexões ao vivo incluídas.

1. Instale o Docker Engine e o plugin do Compose seguindo as [instruções do Docker](https://docs.docker.com/engine/install/).
2. Aponte o registro DNS do seu domínio para a máquina. Abra as portas TCP 80 e 443 e a porta UDP 443 em qualquer firewall à frente dela. O Caddy precisa da porta 80 para obter o certificado.
3. Crie uma pasta para o servidor, baixe os arquivos do lançamento mais recente nela, verifique-os e crie o seu arquivo de configurações:

   ```sh
   sudo mkdir -p /opt/oleafly-server && cd /opt/oleafly-server
   base=https://github.com/Oleafly/oleafly-server/releases/latest/download
   for f in docker-compose.yml Caddyfile env.example litestream.yml SHA256SUMS; do sudo curl -fsSLO "$base/$f"; done
   sha256sum --check --ignore-missing SHA256SUMS
   sudo install -m 600 env.example .env
   ```

4. Edite o `.env` com `sudoedit .env`. Defina `OLEAFLY_DOMAIN` como o seu domínio sem `https://`, defina `OLEAFLY_SERVER_NAME` e preencha pelo menos um [provedor de login](/docs/collaboration/server-access/#sign-in-providers). Deixe vazias as linhas dos provedores que você não usa. Coloque um valor entre aspas simples se ele contiver `$` ou `#`.
5. Inicie-o. A primeira inicialização baixa a imagem do servidor, `ghcr.io/oleafly/oleafly-server`, na versão do lançamento.

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

6. Verifique se ele responde. Isto imprime `200`:

   ```sh
   curl -sS -o /dev/null -w '%{http_code}\n' https://collab.example.org/healthz
   ```

7. [Torne-se o primeiro administrador](#become-the-first-admin). O código de configuração está no log:

   ```sh
   sudo docker compose logs oleafly-server | grep 'Setup code'
   ```

Os seus dados ficam no volume do Docker `oleafly-server_oleafly-data`. O Caddy mantém os certificados dele em `oleafly-server_caddy-data`.

O Docker abre as portas 80 e 443 sozinho, mesmo quando um firewall de host como o `ufw` está ativo. É isso que o Caddy precisa. Não adicione uma entrada `ports:` ao serviço `oleafly-server`. Para alcançar o servidor a partir da própria máquina, publique-o como `127.0.0.1:8080:8080` para que ele fique fora da rede.

Se você mudar o `Caddyfile`, execute `sudo docker compose up -d --force-recreate caddy`. Para atualizar depois, baixe os arquivos do novo lançamento da mesma forma e execute `sudo docker compose up -d` de novo.

### Mantenha os segredos fora do .env

Sete configurações podem conter segredos: `OLEAFLY_SETUP_CODE`, `OLEAFLY_GITHUB_CLIENT_SECRET`, `OLEAFLY_OIDC_<NAME>_CLIENT_SECRET`, `OLEAFLY_SMTP_URL`, `OLEAFLY_BLOB_STORE`, `OLEAFLY_S3_ACCESS_KEY_ID` e `OLEAFLY_S3_SECRET_ACCESS_KEY`. Cada uma também tem uma versão `_FILE` que nomeia um arquivo com o valor. Defina uma das duas, não ambas.

Por exemplo, para passar o segredo de cliente do GitHub como um Docker secret, salve-o em `secrets/github_client_secret` ao lado do `docker-compose.yml`, permita que o usuário do servidor (ID 10001) o leia e exclua a linha `OLEAFLY_GITHUB_CLIENT_SECRET` do `.env`:

```sh
sudo chown 10001:10001 secrets/github_client_secret
sudo chmod 400 secrets/github_client_secret
```

Depois crie `docker-compose.override.yml` ao lado do `docker-compose.yml`. O Compose o lê automaticamente, e o instalador o deixa em paz quando atualiza os outros arquivos.

```yaml
services:
  oleafly-server:
    environment:
      OLEAFLY_GITHUB_CLIENT_SECRET_FILE: /run/secrets/github_client_secret
    secrets:
      - github_client_secret

secrets:
  github_client_secret:
    file: ./secrets/github_client_secret
```

Execute `sudo docker compose up -d` de novo.

## Coolify

O Coolify coloca o próprio proxy à frente do servidor e obtém o certificado, então esta configuração não tem Caddy. O Coolify pode compilar o servidor a partir do repositório do Oleafly, ou executar a [imagem publicada](#deploy-the-published-image), o que pula a compilação.

Antes de começar, aponte o registro DNS do seu domínio, como `collab.example.org`, para o servidor Coolify. Depois crie o aplicativo OAuth do GitHub como descrito em [GitHub](/docs/collaboration/server-access/#github), com o endereço de retorno de chamada `https://collab.example.org/auth/callback/github`. Tenha à mão o ID de cliente e o segredo dele.

### Compilar a partir do repositório

1. No seu projeto do Coolify, selecione **+ New**, depois **Public Repository**, e insira `https://github.com/Oleafly/Oleafly`. Mantenha o branch `main`.
2. Defina **Build Pack** como **Docker Compose**, **Base Directory** como `/` e **Docker Compose Location** como `/deploy/server/docker-compose.coolify.yml`, e depois selecione **Continue**.
3. Em **Advanced › Build**, defina **Build arguments** como **Managed manually in Dockerfile**. A imagem do servidor não precisa de argumentos de compilação. Deixado no automático, o Coolify grava todas as variáveis, segredos incluídos, no histórico de compilação da imagem.
4. Em **General**, defina o domínio do `oleafly-server` como `https://collab.example.org:8080` e salve. O `:8080` diz ao proxy do Coolify em qual porta o servidor escuta. As pessoas ainda se conectam na porta HTTPS de sempre, e o Coolify define `OLEAFLY_PUBLIC_URL` como `https://collab.example.org` para você.
5. Em **Environment Variables**, preencha `OLEAFLY_SERVER_NAME`, que o Coolify marca como obrigatória, depois `OLEAFLY_GITHUB_CLIENT_ID` e `OLEAFLY_GITHUB_CLIENT_SECRET`. Deixe vazias as variáveis que você não usa.
6. Selecione **Deploy**. A primeira compilação constrói o servidor e leva alguns minutos. Quando termina, o Coolify mostra o recurso como em execução e saudável.
7. Abra `https://collab.example.org/healthz` em um navegador. Ele mostra `{"status":"ok"}`.
8. Abra **Logs**, escolha o contêiner `oleafly-server` e copie o código da linha mais recente que começa com `Setup code:`.
9. [Torne-se o primeiro administrador](#become-the-first-admin) com esse código.

Se o servidor não inicia, o log dele nomeia a configuração que ele não consegue usar. Quando diz que `OLEAFLY_PUBLIC_URL` não está definida, falta o passo 4. Um domínio que começa com `http://` é recusado, porque o servidor precisa de HTTPS.

Se o Cloudflare está à frente do Coolify, porque o seu registro DNS passa pelo proxy do Cloudflare ou um túnel leva ao proxy do Coolify, defina `OLEAFLY_PROXY_HOPS` como `2`. Sem isso, o registro de segurança mostra o endereço do proxy para todos, e todos compartilham um limite de login.

O arquivo do Coolify tem espaço para o GitHub e um provedor OpenID Connect chamado `UNIVERSITY`. Defina `OLEAFLY_OIDC_UNIVERSITY_LABEL` como o texto que as pessoas devem ver, como `GitLab`. O endereço de retorno de chamada dele termina em `/auth/callback/university`. Para mais provedores, faça o deploy a partir de um fork com a sua própria cópia do arquivo.

Os dados ficam em um volume do Docker cujo nome termina em `oleafly-data`. Encontre-o com `docker volume ls --filter name=oleafly-data`. A imagem não tem shell, então o **Terminal** do Coolify não consegue abrir um no contêiner do servidor. Os logs e a verificação de integridade funcionam como de costume.

### Implantar a imagem publicada

Executar a imagem publicada pula a compilação, o que serve para um servidor Coolify pequeno. Siga os passos acima com duas mudanças. No passo 2, defina **Docker Compose Location** como `/deploy/server/docker-compose.coolify-image.yml`. Pule o passo 3, porque nada é compilado. O arquivo segue uma série de lançamentos, então cada **Redeploy** baixa o lançamento mais recente dela.

## Render

O [Deploy to Render](https://render.com/deploy?repo=https://github.com/Oleafly/Oleafly) lê o Blueprint no repositório do Oleafly. Ele cria um serviço web a partir da imagem publicada, com um disco de 1 GB para a pasta de dados. O Render anexa discos somente a tipos de instância pagos, então o serviço começa no menor deles, na região do Oregon do Render. Para outra região, faça o deploy a partir de um fork com `region` definido no `render.yaml`.

1. Abra o link e faça login no Render.
2. O Render pede `OLEAFLY_SERVER_NAME` e o ID e o segredo de cliente do GitHub. Preencha o nome e deixe os campos do GitHub vazios por enquanto. O endereço de retorno de chamada deles depende do endereço do serviço, que você ainda não tem.
3. Selecione **Deploy Blueprint**. Quando o serviço estiver no ar, a página dele mostra o endereço, como `https://oleafly-server.onrender.com`. O Blueprint define `OLEAFLY_PUBLIC_URL` com esse endereço.
4. Crie o aplicativo OAuth do GitHub como descrito em [GitHub](/docs/collaboration/server-access/#github), com esse endereço seguido de `/auth/callback/github` como endereço de retorno de chamada. Adicione o ID e o segredo de cliente em **Environment** do serviço. O Render reinicia o servidor com eles.
5. Encontre a linha `Setup code:` mais recente nos **Logs** do serviço e [torne-se o primeiro administrador](#become-the-first-admin).

Se você der ao serviço o seu próprio domínio, defina `OLEAFLY_PUBLIC_URL` como ele em **Environment** e mude o endereço de retorno de chamada no GitHub para corresponder.

Por causa do disco, o Render para o servidor em execução antes de iniciar o novo, então cada deploy tira o servidor do ar por alguns segundos. O Oleafly se reconecta sozinho.

## Railway

O Railway executa a imagem publicada, com um volume para a pasta de dados.

1. Em um projeto do Railway, selecione **+ New**, depois **Docker Image**, e insira `ghcr.io/oleafly/oleafly-server:latest`. Para escolher quando atualizar, use em vez disso a tag própria de um lançamento da [página de lançamentos](https://github.com/Oleafly/Oleafly/releases). O Railway pode iniciar um primeiro deploy imediatamente. Ele para com `OLEAFLY_PUBLIC_URL is not set`, o que é esperado neste ponto.
2. Abra o serviço. Em **Settings › Networking**, selecione **Generate Domain** e insira a porta `8080`. O Railway mostra o endereço, como `oleafly-server-production.up.railway.app`.
3. Em **Settings › Deploy**, defina **Healthcheck Path** como `/readyz`.
4. Clique com o botão direito na área do projeto, adicione um volume, anexe-o ao serviço do servidor e defina o ponto de montagem dele como `/data`.
5. Em **Variables**, abra o **Raw Editor** e cole estas linhas com o nome do seu próprio servidor. Para os valores do GitHub, siga [GitHub](/docs/collaboration/server-access/#github). O endereço de retorno de chamada é o seu endereço do passo 2 com `https://` na frente e `/auth/callback/github` depois.

   ```ini
   OLEAFLY_PUBLIC_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}
   OLEAFLY_BIND=0.0.0.0:8080
   OLEAFLY_DATA_DIR=/data
   OLEAFLY_BEHIND_PROXY=true
   OLEAFLY_SERVER_NAME=Smith Lab
   OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId
   OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret
   PORT=8080
   RAILWAY_RUN_UID=0
   ```

   O Railway monta volumes como root. `RAILWAY_RUN_UID=0` executa o servidor como root para que ele possa gravar no volume.

6. Faça o deploy das mudanças. Encontre a linha `Setup code:` mais recente nos **Deploy Logs** do serviço e [torne-se o primeiro administrador](#become-the-first-admin).

## Linux sem Docker

Em uma máquina sem Docker, o servidor executa como um programa único sob o systemd, com o Caddy à frente para HTTPS.

### Baixar o servidor

Cada lançamento do servidor na [página de lançamentos](https://github.com/Oleafly/Oleafly/releases) tem um programa pronto para x86-64 e para ARM, e um arquivo `SHA256SUMS` para verificá-lo. O programa não precisa de mais nada instalado.

Baixe o arquivo compactado para a sua máquina, terminando em `x86_64-unknown-linux-musl.tar.gz` ou `aarch64-unknown-linux-musl.tar.gz`, e o `SHA256SUMS` para uma pasta. Depois verifique e instale. Em uma máquina ARM, use `aarch64` no lugar de `x86_64`:

```sh
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf oleafly-server-*-x86_64-unknown-linux-musl.tar.gz
sudo install -m 0755 oleafly-server-*-x86_64-unknown-linux-musl/oleafly-server /usr/local/bin/oleafly-server
oleafly-server --version
```

Com a CLI do GitHub instalada, `gh attestation verify oleafly-server-*-x86_64-unknown-linux-musl.tar.gz --repo Oleafly/Oleafly` também verifica se o GitHub construiu o arquivo compactado a partir do repositório do Oleafly. O arquivo compactado inclui a unidade do systemd, `oleafly-server.service`.

Para construir o programa você mesmo, execute isto a partir de um clone do repositório do Oleafly em qualquer computador com Docker. Use `--platform linux/arm64` para um servidor ARM.

```sh
docker buildx build --platform linux/amd64 --target binary --output type=local,dest=dist -f crates/oleafly-server/Dockerfile .
```

Isso grava `dist/oleafly-server`. Copie-o para `/usr/local/bin/oleafly-server` no servidor e torne-o executável.

### Executar com systemd

1. Crie o arquivo de configurações. Somente o root pode lê-lo:

   ```sh
   sudo install -d -m 0755 /etc/oleafly-server
   sudo install -m 0600 /dev/null /etc/oleafly-server/oleafly-server.env
   sudoedit /etc/oleafly-server/oleafly-server.env
   ```

   Coloque uma configuração por linha. `OLEAFLY_BIND=127.0.0.1:8080` mantém o servidor fora da rede, de modo que só o Caddy consiga alcançá-lo. Não defina `OLEAFLY_DATA_DIR`, porque a unidade o define.

   ```ini
   OLEAFLY_PUBLIC_URL=https://collab.example.org
   OLEAFLY_BIND=127.0.0.1:8080
   OLEAFLY_BEHIND_PROXY=true
   OLEAFLY_SERVER_NAME=Smith Lab
   OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId
   OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret
   ```

2. Instale e inicie a unidade a partir do arquivo descompactado, ou de `deploy/server` em um clone do repositório. Depois encontre o código de configuração:

   ```sh
   sudo install -m 0644 oleafly-server.service /etc/systemd/system/oleafly-server.service
   sudo systemctl daemon-reload
   sudo systemctl enable --now oleafly-server
   sudo journalctl -u oleafly-server | grep 'Setup code'
   ```

A unidade executa o servidor como um usuário que o systemd cria para ele, com uma visão somente leitura do resto do sistema. O único lugar onde ele pode gravar é `/var/lib/oleafly-server`, onde ele guarda os dados dele. No disco, essa pasta é `/var/lib/private/oleafly-server`.

Para manter o segredo de cliente fora do arquivo de configurações, use uma credencial do systemd. Salve o segredo em `/etc/oleafly-server/github-client-secret` com modo 600, exclua a linha `OLEAFLY_GITHUB_CLIENT_SECRET` do arquivo de configurações, execute `sudo systemctl edit oleafly-server` e adicione:

```ini
[Service]
LoadCredential=github-client-secret:/etc/oleafly-server/github-client-secret
Environment=OLEAFLY_GITHUB_CLIENT_SECRET_FILE=%d/github-client-secret
```

Depois execute `sudo systemctl restart oleafly-server`.

### Coloque HTTPS na frente

Instale o Caddy com as [instruções dele para a sua distribuição](https://caddyserver.com/docs/install). Substitua o `/etc/caddy/Caddyfile` por estas linhas e execute `sudo systemctl reload caddy`. O Caddy obtém o certificado e repassa as conexões ao vivo.

```
collab.example.org {
	reverse_proxy 127.0.0.1:8080
}
```

Para nginx ou Apache, ou um servidor web que a sua universidade já executa, leia [Atrás de um proxy reverso](/docs/collaboration/server-operations/#behind-a-reverse-proxy).

## Sem endereço público

Se a máquina não tem endereço público, por exemplo um computador no seu laboratório atrás do firewall da universidade, o Cloudflare Tunnel pode torná-la alcançável. Você precisa de uma conta do Cloudflare com o seu domínio nela. O Cloudflare cuida do HTTPS para o nome de host, então as requisições são descriptografadas na rede do Cloudflare antes de chegarem à sua máquina. Conte o Cloudflare entre as partes que podem ler o tráfego para o seu servidor.

1. Siga os passos de [Docker Compose à mão](#docker-compose-by-hand) até a edição do `.env`. Defina `OLEAFLY_DOMAIN` como o nome de host que você usará, como `collab.example.org`. O instalador de um comando não serve aqui, porque ele inicia o Caddy.
2. Inicie somente o servidor. O Caddy não é necessário aqui:

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

3. No painel do Cloudflare, vá em **Networking › Tunnels**, selecione **Create Tunnel**, dê um nome a ele e selecione **Create Tunnel** de novo. Copie o token do comando de instalação que ele mostra.
4. Inicie o túnel ao lado do servidor. O comando `read` espera você colar o token e não o mostra:

   ```sh
   read -rs TUNNEL_TOKEN && export TUNNEL_TOKEN
   sudo --preserve-env=TUNNEL_TOKEN docker run -d --name oleafly-tunnel --restart unless-stopped --network oleafly-server_default -e TUNNEL_TOKEN cloudflare/cloudflared:2026.10.0 tunnel --no-autoupdate run
   ```

5. De volta ao painel, abra o túnel. Em **Routes**, selecione **Add route** e depois **Published application**. Em **Hostname**, insira o subdomínio e escolha o seu domínio. Defina **Service URL** como `http://oleafly-server:8080` e selecione **Add route**.
6. Verifique se ele responde em `https://collab.example.org/healthz`, depois [torne-se o primeiro administrador](#become-the-first-admin).

Em uma máquina sem Docker, instale o `cloudflared` do [repositório de pacotes do Cloudflare](https://pkg.cloudflare.com/), execute `sudo cloudflared service install` seguido do token e defina **Service URL** como `http://127.0.0.1:8080`.

O Cloudflare repassa as conexões ao vivo e coloca o endereço do visitante por último no `X-Forwarded-For`, então mantenha `OLEAFLY_BEHIND_PROXY=true`. Quando o túnel leva a outro proxy, como o do Coolify, e não direto ao servidor, defina também `OLEAFLY_PROXY_HOPS=2`. O Cloudflare recusa requisições maiores que 100 MB nos planos Free e Pro dele, então defina `OLEAFLY_MAX_PROJECT_MB` como 100 ou menos, ou projetos grandes falham ao enviar. Não coloque o Cloudflare Access à frente do servidor, porque o Oleafly não consegue passar da página de login dele.

Quando você atualizar o servidor mais tarde, baixe os arquivos do novo lançamento e nomeie o serviço para manter o Caddy fora: `sudo docker compose up -d oleafly-server`.

## Torne-se o primeiro administrador

Um servidor novo não tem administrador. Até alguém concluir a configuração, o servidor cria um novo código de configuração de uso único a cada vez que inicia e o grava no log dele.

1. Encontre no log a linha mais recente que começa com `Setup code:`:
   - Instalação com um comando: o instalador o imprime quando termina. Para vê-lo de novo, execute `cd /opt/oleafly-server && sudo docker compose logs oleafly-server | grep 'Setup code'`
   - Docker Compose à mão: `sudo docker compose logs oleafly-server | grep 'Setup code'` na pasta do servidor
   - Coolify: os logs do serviço `oleafly-server`
   - systemd: `sudo journalctl -u oleafly-server | grep 'Setup code'`
2. No Oleafly, abra **Configurações → Colaboração**, selecione **Adicionar servidor** e insira o endereço do seu servidor. O Oleafly vê que o servidor precisa de configuração e pede o **Código de configuração**.
3. Digite o código e faça login com qualquer provedor que você tenha configurado. Você se torna o administrador do servidor, e o código para de funcionar.

Qualquer pessoa que tenha o código antes de você usá-lo pode se tornar administradora, então cole-o somente no Oleafly.

Você também pode escolher o código você mesmo com `OLEAFLY_SETUP_CODE`: pelo menos 12 letras ou dígitos, com traços ou espaços se quiser. O servidor então nunca o imprime. O log apenas diz `Setup code: set by OLEAFLY_SETUP_CODE`, e você digita o valor que defini. Remova-o das suas configurações quando a configuração terminar.

Depois, deixe as pessoas entrarem. [Login e acesso](/docs/collaboration/server-access/#access-rules) explica como.

## Verifique o servidor

- Com a instalação de um comando, `sudo sh /opt/oleafly-server/install.sh status` verifica os contêineres e o HTTPS de uma vez.
- `https://collab.example.org/healthz` responde `200` enquanto o processo do servidor executa.
- `/readyz` responde `200` somente enquanto o servidor consegue gravar no banco de dados e na pasta de dados dele. Quando não consegue, por exemplo com o disco cheio, ele responde `503` e nomeia o que falhou, `database` ou `storage`.
- A imagem do Docker verifica `/readyz` sozinha, então `docker ps` e o Coolify mostram um servidor não íntegro em vez de um em execução que não consegue salvar nada.
- No Oleafly, **Testar conexão** em **Configurações → Colaboração** verifica o endereço, o HTTPS, a versão, as conexões ao vivo, as opções de login e o relógio do servidor. **Testes de conexão** no [console de administração](/docs/collaboration/server-access/#admin-console) executa as mesmas verificações.
