Como instalar o ownCloud Infinite Scale com Docker Compose no Ubuntu

Você conclui a instalação do Docker Compose, executa o comando docker compose up -de ainda não consegue acessar o ownCloud. Esse é o padrão de falha prática mais comum com o Infinite Scale: os contêineres podem existir, mas problemas com DNS, TLS, caminhos de armazenamento ou alguma variável de ambiente necessária impedem que a infraestrutura se torne utilizável.

Este guia utiliza a abordagem Docker Compose orientada à produção, documentada pela ownCloud, para uma implantação em servidor único. A página de documentação atual da ownCloud está publicada na seção de documentação de desenvolvimento da versão 9.0, mas indica explicitamente que o exemplo de produção disponível para download utiliza a versão estável mais recente e, atualmente, aponta para a branch estável 8.2. Essa distinção é importante: não copie as tags da imagem de desenvolvimento para um servidor de produção, a menos que você queira intencionalmente uma versão de desenvolvimento.

A configuração abaixo é adequada para uso doméstico e pequenas organizações que desejam uma instância do Infinite Scale por trás de um proxy reverso com HTTPS. Ela pressupõe o uso do Ubuntu LTS, Docker Engine, o plugin Docker Compose, um domínio controlado pelo usuário e acesso de administrador ao servidor. O exemplo de produção do ownCloud recomenda aproximadamente 4 a 6 GB de RAM para os serviços padrão habilitados e requer, no mínimo, o domínio ownCloud; integrações opcionais para escritórios exigem seus próprios subdomínios.

Antes de começar: resolva primeiro as questões de rede e armazenamento.

Não comece baixando os arquivos do Compose. Primeiro, confirme os itens mais difíceis de corrigir depois que o stack já estiver em execução:

• DNS: o nome de host escolhido, como ocis.example.com, deve ser resolvido para o endereço IP público do servidor.
• Firewall e NAT: uma instalação voltada para a internet precisa que as portas TCP 80 e 443 estejam acessíveis para o proxy reverso e o fluxo de certificados. Normalmente, é necessário SSH na porta TCP 22 para administração.
• Armazenamento persistente: os volumes gerenciados pelo Docker são convenientes, mas os sistemas de produção geralmente se beneficiam de caminhos definidos para dados de configuração e do usuário, facilitando backups e planejamento de capacidade.
• Remetente de e-mail: o exemplo documentado do ownCloud exige SMTP_SENDERque ele seja configurado, mesmo que você ainda não tenha configurado um servidor SMTP de retransmissão em funcionamento.

Esses requisitos estão documentados no guia oficial de instalação do servidor ownCloud Infinite Scale . Para o Docker em si, utilize as instruções de instalação atuais do Docker Engine para Ubuntu e as instruções do plugin Compose, em vez de depender de pacotes de distribuição potencialmente mais antigos.

1. Verifique o Docker e o Docker Compose.

No servidor, primeiro atualize o sistema operacional e, em seguida, verifique se o Docker Engine e o plugin Compose estão disponíveis:

sudo apt-get update && sudo apt-get upgrade
docker --version
docker compose version

O importante não é o número da versão exibido por esses comandos. Você está confirmando que ambos os comandos foram executados com sucesso e que o Compose está disponível docker compose. O guia do ownCloud recomenda instalar o Docker a partir do repositório oficial do Docker, em vez de depender dos pacotes Docker embutidos no Ubuntu, que podem estar desatualizados.

2. Baixe o exemplo oficial e estável do Compose.

O ownCloud fornece um exemplo completo de implantação do Compose, em vez de exigir que os administradores criem uma infraestrutura de produção do zero. No momento da verificação, a documentação indica que o download de produção atual é baseado na stable-8.2branch, pois a documentação da versão 9.0 ainda está marcada como em desenvolvimento.

O fluxo de trabalho oficial baixa o deployments/examples/ocis_fulldiretório, transfere o arquivo resultante para o servidor e o extrai em um caminho como /opt/compose/ocis/ocis_full. O nome exato do arquivo pode mudar com a versão estável, portanto, use o link de download mostrado na documentação atual do ownCloud em vez de inserir um nome de arquivo fixo de um tutorial antigo.

Após a extração, acesse o diretório de implantação e inspecione o conteúdo:

cd /opt/compose/ocis/ocis_full
ls -la

Você deverá ver os arquivos Compose, o diretório de configuração e .envo arquivo fornecidos pelo exemplo. Se estiver atualizando um exemplo extraído já existente, faça um backup .envprimeiro; o ownCloud avisa que extrair um pacote mais recente pode sobrescrevê-lo.

3. Configure o arquivo .env com cuidado.

A maioria dos problemas iniciais de inicialização surge do arquivo de ambiente. Edite-o .envno diretório extraído e configure as opções em uma ordem específica.

Defina o domínio público.

Defina OCIS_DOMAINo nome do host que já resolve para o servidor, por exemplo, `https://example.com` ocis.example.com. Se você habilitar o Collabora ou o ONLYOFFICE, configure também os nomes de host documentados para eles. Não use um domínio .envque seja diferente dos seus registros DNS.

Preparar TLS

Para uma implementação voltada para a internet, o exemplo oficial usa Traefik e Let's Encrypt. Defina TRAEFIK_ACME_MAILum endereço de e-mail real que você controle. A ownCloud recomenda usar primeiro a Autoridade Certificadora (CA) de teste do Let's Encrypt, confirmando que a emissão do certificado funciona, e somente então migrar para a produção. Isso reduz a chance de atingir os limites de taxa do Let's Encrypt durante a solução de problemas.

Selecione os locais de dados e configuração.

Se você deseja armazenamento montado no host, defina OCIS_CONFIG_DIRos OCIS_DATA_DIRcaminhos persistentes planejados. Certifique-se de que o sistema de arquivos subjacente tenha capacidade suficiente e que seu processo de backup inclua tanto a configuração quanto os dados.

Defina um remetente SMTP

No mínimo, defina SMTP_SENDER. Você pode adicionar o host SMTP completo, a porta, o nome de usuário, a senha, o método de autenticação e as configurações de segurança quando estiver pronto para enviar notificações.

4. Valide a configuração do Compose e, em seguida, inicie o stack.

Antes de baixar e iniciar os contêineres, peça ao Compose para renderizar e validar a configuração montada:

docker compose config

Se isso falhar, corrija a sintaxe ou as variáveis ​​ausentes antes de continuar. Essa verificação é muito mais rápida do que diagnosticar uma implantação parcialmente iniciada.

Quando a configuração for renderizada com sucesso, inicie a implantação no modo desanexado:

docker compose up -d

O Compose irá baixar as imagens necessárias e iniciar os serviços definidos pelo exemplo. Na primeira execução, isso pode demorar mais, pois as imagens precisam ser baixadas e certificados podem ser solicitados.

Se a primeira tentativa falhar, solucione o problema da maneira mais fácil para a mais difícil.

Verificar estado do contêiner

Comece pela visualização "Compor" em vez de tentar adivinhar qual serviço falhou:

docker compose ps -a --format "table {{.Service}}	{{.State}}	{{.ID}}"

Um serviço que é encerrado repetidamente é mais útil do que um erro do navegador, pois permite restringir o problema a um único contêiner.

Leia os logs do Traefik em busca de problemas com certificados.

O guia do ownCloud recomenda especificamente verificar o Traefik primeiro quando o HTTPS não estiver funcionando. As causas típicas incluem um e-mail de contato ACME inválido, portas 80/443 fechadas ou DNS que retorna NXDOMAIN ou aponta para o IP errado. Após corrigir um problema com o ACME, siga as instruções oficiais para remover apenas o volume de certificado que contém os dados do teste com falha. Não exclua todos os volumes.

Verifique os registros do serviço ownCloud.

Encontre o ID do contêiner com docker compose ps, depois inspecione seus registros:

docker logs -f <container_id>

O processo de inicialização pode criar a configuração inicial na primeira execução. O ownCloud documenta o padrão de comando ocis init || true; ocis serverpara implantações do Compose, de modo que a inicialização seja ignorada quando a configuração já existir.

Não use o comando `docker compose down -v` de forma leviana.

Para interromper a implantação, use:

docker compose down --remove-orphans

Não adicione -vvolumes a menos que deseje removê-los intencionalmente. O ownCloud avisa explicitamente que isso pode excluir dados de implantação. Se for necessário remover um volume de certificado descartável durante a solução de problemas de TLS, exclua-o seletivamente.

Como verificar se a instalação foi realmente concluída

Uma docker compose up -dverificação bem-sucedida requer apenas uma etapa. Verifique o resultado em quatro níveis:

1. DNS: o nome de host público resolve para o endereço correto do servidor.
2. TLS: o navegador acessa o site via HTTPS sem aviso de certificado. Se você usou intencionalmente a CA de teste do Let's Encrypt, verifique primeiro o certificado de teste e, em seguida, altere para o certificado de produção conforme documentado.
3. Contêineres: docker compose ps -a mostra os serviços esperados em execução, em vez de reinicializados ou encerrados.
4. Aplicação: você pode abrir o URL do ownCloud configurado, fazer login com as credenciais de administrador iniciais que você definiu ou recuperou, criar uma pasta e carregar um pequeno arquivo de teste.

Para uma nova instalação, a documentação indica que o nome de usuário padrão do administrador é <username> admin, e a senha pode ser definida manualmente durante a configuração ou obtida através do log de inicialização/procedimentos de redefinição documentados. Altere a senha inicial imediatamente e não deixe uma instalação de produção com as credenciais padrão conhecidas.

Após o serviço básico de arquivos estar funcionando, adicione componentes de colaboração opcionais ou integrações mais avançadas. Fazer isso depois que a implantação principal estiver funcionando corretamente facilita muito a solução de problemas, pois uma falha em um pacote de escritório, provedor de identidade externo ou serviço antivírus não estará mais misturada com problemas básicos de DNS e TLS.

Notas de manutenção para uma implantação estável

Antes de uma atualização, faça backup de seus dados e configurações e leia as notas de migração específicas da versão. A documentação do ownCloud distingue entre atualizações de rotina de imagens e upgrades que podem exigir alterações de configuração. Uma sequência comum de manutenção é interromper o sistema, baixar as imagens e reiniciar com a limpeza de instâncias órfãs, mas você ainda deve consultar o guia de atualização específico da versão antes de alterar a versão.

Para um servidor de produção, monitore também o uso do disco. Volumes gerenciados pelo Docker são fáceis de configurar inicialmente, mas o crescimento do armazenamento pode surpreender quando o sistema operacional e os arquivos do usuário compartilham o mesmo sistema de arquivos. Se você espera um volume substancial de dados, use caminhos de armazenamento dedicados desde o início ou migre-os usando o procedimento de volume documentado e a propriedade correta para o usuário do contêiner.