Pular para o conteúdo
Oleaflyv0.4.12

Executar um servidor

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

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.

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

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 (abre em uma nova guia). O servidor como um programa Linux único está na página de lançamentos do Oleafly (abre em uma nova guia).

OpçãoQuando usar
Um comandoUma 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ãoVocê prefere colocar e editar cada arquivo você mesmo.
CoolifyVocê já administra um servidor Coolify.
Render ou RailwayVocê prefere pagar um serviço de hospedagem a cuidar de uma máquina.
Linux sem DockerUma 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 lista todas elas.

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

O que o instalador fazO instalador executa seis etapas em ordem. Ele confere se a máquina roda Linux em x86-64 ou ARM, com as portas 80 e 443 livres. Instala o Docker se ele estiver faltando, depois de perguntar. Baixa os arquivos da release e confere cada um com o SHA256SUMS. Pergunta o domínio, o nome do servidor, como as pessoas entram e, opcionalmente, o e-mail. Grava as configurações no .env e inicia o servidor com o Caddy em /opt/oleafly-server. Quando o servidor responde por HTTPS, ele exibe o código de configuração do primeiro administrador.Verificar a máquinaLinux, x86-64 ou ARMPortas 80 e 443 livresDockerInstalado se estiver faltando,depois de perguntar a vocêBaixar e conferirOs arquivos da release,conferidos pelo SHA256SUMSAlgumas perguntasDomínio, nome do servidor,login, e-mailIniciarServidor e Caddyem /opt/oleafly-serverCódigo de configuraçãoExibido quando oservidor respondeO que o instalador fazO instalador executa seis etapas em ordem. Ele confere se a máquina roda Linux em x86-64 ou ARM, com as portas 80 e 443 livres. Instala o Docker se ele estiver faltando, depois de perguntar. Baixa os arquivos da release e confere cada um com o SHA256SUMS. Pergunta o domínio, o nome do servidor, como as pessoas entram e, opcionalmente, o e-mail. Grava as configurações no .env e inicia o servidor com o Caddy em /opt/oleafly-server. Quando o servidor responde por HTTPS, ele exibe o código de configuração do primeiro administrador.Verificar a máquinaLinux, x86-64 ou ARMPortas 80 e 443 livresDockerInstalado se estiver faltando,depois de perguntar a vocêBaixar e conferirOs arquivos da release,conferidos pelo SHA256SUMSAlgumas perguntasDomínio, nome do servidor,login, e-mailIniciarServidor e Caddyem /opt/oleafly-serverCódigo de configuraçãoExibido quando oservidor responde
Um comando: verificar, Docker, baixar e conferir, algumas perguntas, iniciar e então o código de configuração.

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

Depois execute:

Janela do terminal
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 (abre em uma nova guia) 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.

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.

Se a sua instituição não permite canalizar um script para um shell, baixe install.sh e SHA256SUMS do lançamento mais recente (abre em uma nova guia) para uma pasta. Verifique o script, leia-o e depois execute-o:

Janela do terminal
sha256sum --check --ignore-missing SHA256SUMS
sudo sh install.sh

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.

Janela do terminal
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: 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 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.

    Janela do terminal
    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 (abre em uma nova guia) com o que ele imprimiu.

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.

Implantação com Docker ComposeO Oleafly de cada computador se conecta por HTTPS ao Caddy na sua máquina. O Caddy guarda o certificado e repassa as solicitações por HTTP simples ao contêiner oleafly-server. O servidor guarda o banco de dados e os arquivos em um volume de dados do Docker, e pode guardar os arquivos em um bucket S3.Sua máquina, com Docker ComposeOleaflyEm cadacomputadorCaddyHTTPScertificadooleafly-serverConfigurações no .envVolume de dadosBanco de dados,arquivosBucket S3OpcionalImplantação com Docker ComposeO Oleafly de cada computador se conecta por HTTPS ao Caddy na sua máquina. O Caddy guarda o certificado e repassa as solicitações por HTTP simples ao contêiner oleafly-server. O servidor guarda o banco de dados e os arquivos em um volume de dados do Docker, e pode guardar os arquivos em um bucket S3.Sua máquina, com Docker ComposeOleaflyEm cada computadorCaddyCertificado HTTPSoleafly-serverConfigurações no .envVolume de dadosBanco de dados, arquivosBucket S3Opcional, arquivosHTTPSHTTP
Docker Compose: o Caddy cuida do HTTPS na frente do servidor, e o volume de dados guarda o banco de dados e os arquivos.
  1. Instale o Docker Engine e o plugin do Compose seguindo as instruções do Docker (abre em uma nova guia).

  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:

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

    Janela do terminal
    sudo docker compose up -d
  6. Verifique se ele responde. Isto imprime 200:

    Janela do terminal
    curl -sS -o /dev/null -w '%{http_code}\n' https://collab.example.org/healthz
  7. Torne-se o primeiro administrador. O código de configuração está no log:

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

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:

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

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.

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, o que pula a compilação.

Implantação com CoolifyO Oleafly de cada computador se conecta, opcionalmente pelo Cloudflare, ao proxy do Coolify, que cuida do HTTPS e repassa as solicitações ao oleafly-server. O servidor guarda os dados em um volume do Docker. Quando o Cloudflare fica na frente do proxy do Coolify, cada solicitação passa por dois proxies, então defina OLEAFLY_PROXY_HOPS como 2.OleaflyEm cadacomputadorCloudflareOpcionalProxy do CoolifyHTTPSoleafly-serverNo servidordo seu CoolifyVolume de dadosCom os dois na frente, definaOLEAFLY_PROXY_HOPS=2Implantação com CoolifyO Oleafly de cada computador se conecta, opcionalmente pelo Cloudflare, ao proxy do Coolify, que cuida do HTTPS e repassa as solicitações ao oleafly-server. O servidor guarda os dados em um volume do Docker. Quando o Cloudflare fica na frente do proxy do Coolify, cada solicitação passa por dois proxies, então defina OLEAFLY_PROXY_HOPS como 2.OleaflyEm cada computadorCloudflareOpcionalProxy do CoolifyHTTPSoleafly-serverNo servidor do seu CoolifyVolume de dadosCom os dois na frente, definaOLEAFLY_PROXY_HOPS=2
Coolify: o proxy dele cuida do HTTPS. Com o Cloudflare também na frente, defina OLEAFLY_PROXY_HOPS=2.

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

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

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.

O Deploy to Render (abre em uma nova guia) 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, 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.

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.

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 (abre em uma nova guia). 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. O endereço de retorno de chamada é o seu endereço do passo 2 com https:// na frente e /auth/callback/github depois.

    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.

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

Implantação no Linux sem DockerO Oleafly de cada computador se conecta por HTTPS ao Caddy na sua máquina Linux. O Caddy repassa as solicitações ao oleafly-server, que roda como um serviço do systemd escutando em 127.0.0.1, porta 8080, e guarda os dados em /var/lib/oleafly-server.Sua máquina LinuxOleaflyEm cadacomputadorCaddyHTTPScertificadooleafly-serverServiço do systemdPasta de dados/var/lib/oleafly-serverImplantação no Linux sem DockerO Oleafly de cada computador se conecta por HTTPS ao Caddy na sua máquina Linux. O Caddy repassa as solicitações ao oleafly-server, que roda como um serviço do systemd escutando em 127.0.0.1, porta 8080, e guarda os dados em /var/lib/oleafly-server.Sua máquina LinuxOleaflyEm cada computadorCaddyCertificado HTTPSoleafly-serverServiço do systemdPasta de dados/var/lib/oleafly-serverHTTPSHTTP
Linux sem Docker: o systemd executa o servidor, e o Caddy na frente cuida do HTTPS.

Cada lançamento do servidor na página de lançamentos (abre em uma nova guia) 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:

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

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

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

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

    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:

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

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

Instale o Caddy com as instruções dele para a sua distribuição (abre em uma nova guia). 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.

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.

Implantação com Cloudflare TunnelO Oleafly de cada computador se conecta por HTTPS ao Cloudflare. Um contêiner cloudflared na sua máquina abre um túnel de saída para o Cloudflare, então a máquina não precisa de endereço público. As solicitações chegam pelo túnel ao cloudflared, que as repassa ao oleafly-server.Sua máquina, sem endereço públicoOleaflyEm cadacomputadorCloudflareHTTPScloudflaredAbre o túneloleafly-serverVolume de dadosImplantação com Cloudflare TunnelO Oleafly de cada computador se conecta por HTTPS ao Cloudflare. Um contêiner cloudflared na sua máquina abre um túnel de saída para o Cloudflare, então a máquina não precisa de endereço público. As solicitações chegam pelo túnel ao cloudflared, que as repassa ao oleafly-server.Sua máquina, sem endereço públicoOleaflyEm cada computadorCloudflareHTTPScloudflaredAbre o túneloleafly-serverVolume de dadosTúnel
Cloudflare Tunnel: a sua máquina abre o túnel, então ela não precisa de endereço público.
  1. Siga os passos de Docker Compose à mão 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:

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

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

Em uma máquina sem Docker, instale o cloudflared do repositório de pacotes do Cloudflare (abre em uma nova guia), 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.

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 explica como.

  • 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 executa as mesmas verificações.
Visualização da imagem

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

Tente de novo ou pesquise na documentação.