Como instalar o Cloudron numa VPS Ubuntu

Instalar o Cloudron numa VPS: a versão curta

Para instalar o Cloudron numa VPS, precisa de um servidor Ubuntu novo, de pelo menos 2 GB de RAM e de um domínio cujos registos DNS possa editar. A instalação propriamente dita consiste em três comandos e num reboot. Quase todos os problemas ocorrem antes desse passo (imagem base incorreta, tipo de virtualização incorreto) ou depois dele (DNS, correio eletrónico, backups).

wget https://cloudron.io/cloudron-setup
chmod +x cloudron-setup
sudo ./cloudron-setup

O Cloudron instala, atualiza e faz backups de aplicações self-hosted, além de emitir certificados TLS (transport layer security). Cada aplicação é executada no Docker, o nginx fica à frente de todas elas e cada aplicação recebe o seu próprio subdomínio do domínio. É por isso que o trabalho de DNS vem primeiro neste caso.

Por que o Cloudron é exigente quanto ao sistema operativo base

O script de configuração verifica o servidor antes de instalar qualquer componente. Se uma verificação falhar, terá de encomendar um servidor novo. Leia estes requisitos antes de escolher uma imagem.

• Apenas Ubuntu, e somente três versões. Qualquer outra opção termina com Cloudron requires Ubuntu 20.04, 22.04, 24.04. Debian, Rocky e Alpine não são suportados. O Ubuntu 24.04 requer o Cloudron 8 ou mais recente, e o script verifica isso automaticamente.
• Apenas Intel ou AMD de 64 bits: Error: Cloudron only supports amd64/x86_64. Um VPS com ARM não pode executar o Cloudron.
• Apenas virtualização completa do hardware. Num VPS baseado em contentores, o script para com Error: Cloudron does not support lxc, only runs on bare metal or with full hardware virtualization porque deteta o contentor com systemd-detect-virt --container. KVM é suportado. OpenVZ e LXC não são.
• O sistema de ficheiros raiz tem de ser ext4 ou xfs. Em qualquer outro sistema, verá Error: Cloudron requires '/' to be ext4 or xfs. É assim que as imagens btrfs e zfs falham.
• Pelo menos 941 MB de RAM e 20 GB em /, medidos com free -m e pelo tamanho do sistema de ficheiros raiz.
• Um servidor realmente novo. Se nginx, docker ou node já estiver instalado, o script recusa a instalação com Error: Some packages like nginx/docker/nodejs are already installed..

Esta última verificação é a que costuma gerar mais discussões. Eis o motivo. O Cloudron instala versões fixas do Docker, nginx, Node.js e MySQL, escreve a configuração do nginx para cada aplicação alojada e gere diretamente as regras da firewall iptables. Um Docker instalado por si no dia anterior terá a versão errada, e os ficheiros dos seus sites existentes no nginx serão substituídos. O Cloudron controla toda a máquina, por isso atribua-lhe um VPS dedicado.

Há outra verificação fácil de ignorar. Num CPU antigo sem AVX (extensões vetoriais avançadas), o script apresenta CPU has no AVX support. MongoDB will be disabled, e todas as aplicações que necessitam de MongoDB ficam impossíveis de instalar. Verifique o CPU antes de se comprometer com grep -m1 -o avx /proc/cpuinfo. Num host compatível, este comando apresenta avx; num host antigo, não apresenta nada.

De quanta RAM o Cloudron precisa?

O script recusa-se a executar com menos de 941 MB, com Error: Cloudron requires atleast 1GB physical memory, e a documentação pede 2 GB de RAM e 20 GB de disco. Ambos os valores são o mínimo para a plataforma, não para a plataforma mais as suas aplicações. Antes de instalar uma única aplicação, o Cloudron já está a executar o Docker, o nginx, o seu próprio serviço box, os contentores de bases de dados que disponibiliza às aplicações (MySQL, PostgreSQL, MongoDB), o Redis e a infraestrutura de correio. Execute docker ps numa instalação nova e conte-os.

Os limites de memória das aplicações são aplicados além dessa base. Cada pacote de aplicação é disponibilizado com um limite baixo predefinido, que pode aumentar com o controlo deslizante na vista Resources da aplicação. Quando uma aplicação ultrapassa o seu limite, reinicia e envia uma notificação OOM (out of memory). Por isso, um servidor que reinicia continuamente uma aplicação costuma indicar um problema de limite, não um bug.

Este é o dimensionamento que eu encomendaria. São recomendações para um servidor que não terá de reconstruir no próximo mês. Não são resultados de testes de desempenho medidos.

[
  {
    "label": "2 apps (free tier)",
    "vcpu": 2,
    "ram_gb": 4,
    "disk_gb": 60
  },
  {
    "label": "5 apps",
    "vcpu": 4,
    "ram_gb": 8,
    "disk_gb": 120
  },
  {
    "label": "10 apps",
    "vcpu": 6,
    "ram_gb": 16,
    "disk_gb": 240
  }
]

Duas aplicações funcionam confortavelmente com 4 GB de RAM e 60 GB de disco. Cerca de dez aplicações precisam de 16 GB e 240 GB, porque a base da plataforma nunca diminui e cada aplicação acrescenta uma imagem Docker, uma base de dados e os seus próprios dados. O disco fica cheio mais depressa do que se espera: as imagens, os dados das aplicações e as cópias de segurança locais partilham o mesmo volume até transferir as cópias para fora do servidor.

O Cloudron fornece swap ilimitada a cada aplicação, por isso o limite de memória definido aplica-se apenas à RAM. Numa imagem VPS sem ficheiro de swap, swapon --show não apresenta qualquer saída, e a pressão de memória transforma-se diretamente em reinícios OOM, em vez de tornar a aplicação mais lenta. Adicionar 2 GB de swap é uma medida de segurança económica, mas não substitui a memória real. A diferença entre os planos VPS é pequena quando comparada com as horas que gastará a ajustar limites. Consulte quanto custa realmente um VPS e escolha o tamanho seguinte.

DNS: o registro curinga que faz os subdomínios das aplicações funcionarem

O Cloudron disponibiliza o dashboard em my.example.com e cada aplicação no seu próprio subdomínio. Por isso, o DNS é um pré-requisito, não uma etapa posterior. Aponte estes registos para o endereço IP público do servidor antes de abrir o dashboard pela primeira vez:

• my.example.com como registo A. Este é o dashboard.
• *.example.com como registo A. É este registo que faz os subdomínios das aplicações funcionarem, por isso wiki.example.com e git.example.com são resolvidos assim que instalar essas aplicações.
• example.com como registo A, apenas se quiser uma aplicação no domínio raiz.

Um registo curinga tem precedência inferior à de um registo explícito. Por isso, um www.example.com existente que aponte para outro local continua a funcionar.

Durante a configuração, escolha como o Cloudron vai gerir o DNS a partir desse momento:

• Um fornecedor com API. O Cloudron armazena um token para Cloudflare, DigitalOcean, Route53, Hetzner, Porkbun, Linode, deSEC, Gandi, Namecheap e cerca de vinte outros fornecedores. Depois, cria todos os registos, incluindo os registos de correio.
• Curinga. Adicione manualmente o registo * e o Cloudron não cria nenhum registo.
• Manual. O Cloudron mostra cada registo e aguarda enquanto o adiciona, antes de cada instalação de aplicação.

Um registo DNS curinga não é um certificado curinga. O fornecedor de certificados predefinido é Let's Encrypt Prod - Wildcard, que comprova a posse através do DNS. Por isso, só funciona com um fornecedor com API. Nos backends Wildcard ou Manual, é utilizado um certificado por aplicação, validado através de HTTP. Isto significa que a porta de entrada 80 tem de permanecer aberta permanentemente. Se o seu registrador ou fornecedor de DNS estiver na lista de APIs, utilize-o: os registos de correio e os certificados deixam de ser da sua responsabilidade.

Verifique tudo antes de avançar. dig +short my.example.com e dig +short anything.example.com devem mostrar o endereço IP do servidor. Se a consulta ao registo curinga não mostrar nada, as aplicações vão falhar mais tarde, embora o dashboard continue a funcionar.

Se o domínio estiver atrás do Cloudflare, defina os registos como DNS only. O proxy encaminha apenas HTTP e HTTPS, por isso as portas de correio deixam de funcionar e cada aplicação vê um endereço do Cloudflare em vez do endereço do visitante.

Execute o script de configuração

wget https://cloudron.io/cloudron-setup
chmod +x cloudron-setup
sudo ./cloudron-setup

Execute-o como root ou através de sudo, porque, caso contrário, a primeira coisa que ele imprime é This script should be run as root.. A instalação demora vários minutos e não apresenta saída enquanto é executada, porque a saída do apt e os downloads do Docker são enviados para um ficheiro de log. Monitorize-o a partir de uma segunda sessão SSH:

tail -f /var/log/cloudron-setup.log

No fim, o script imprime After reboot, visit one of the following URLs and accept the self-signed certificate to finish setup. seguido do endereço do seu servidor e pergunta The server has to be rebooted to apply all the settings. Reboot now ? [Y/n]. Responda yes. A flag --skip-reboot existe se precisar de agendar o reinício, mas o Cloudron não pode ser utilizado até o servidor voltar a arrancar.

Primeiro arranque: domínio, backend DNS e conta de administrador

Abra https://<server-ip> e aceite o aviso do navegador. O certificado é autoassinado porque o Cloudron ainda não conhece o seu domínio. Por isso, não tem um nome de domínio para fornecer a uma autoridade certificadora. No Chrome, clique em Advanced e depois em Proceed to <ip> (unsafe). No Firefox, clique em Advanced e depois em Accept the Risk and Continue.

O primeiro ecrã pede o seu domínio. Introduza example.com e o dashboard passa a estar disponível em my.example.com. Também pode utilizar um subdomínio, como cloudron.example.com. Nesse caso, o dashboard fica disponível em my.cloudron.example.com. Selecione o backend DNS, cole o token da API, se tiver um, e crie a conta de administrador com um endereço de e-mail que consulte regularmente. O registo no Let's Encrypt e todos os alertas da plataforma utilizam esse endereço.

Quando guardar, o Cloudron solicita os certificados e move o dashboard para https://my.example.com. O URL com o endereço IP deixa de funcionar nesse momento. Adicione o novo URL aos marcadores.

Certificados: o que é renovado e quando deixa de funcionar

A renovação dos certificados é automática e segue o ACME Renewal Information (ARI), o calendário publicado pela autoridade certificadora. Na prática, a renovação ocorre cerca de um mês antes da expiração. Se a renovação falhar, a conta de administrador recebe um e-mail. Se o certificado expirar, é utilizado o certificado autoassinado integrado. É isso que normalmente causa o aviso do navegador num site que funcionava no dia anterior.

Duas causas respondem pela maioria dos problemas. A validação HTTP precisa da porta de entrada 80. Por isso, fechar a porta 80 porque "tudo já usa HTTPS" interrompe a renovação de todas as aplicações que usam um backend Wildcard ou Manual DNS. A validação DNS precisa de um token de API que continue a ter acesso de escrita. Rodar ou restringir esse token interrompe a renovação silenciosamente, até à chegada do e-mail de aviso.

A vista Domains tem um botão Renew All para forçar imediatamente a tentativa e um provedor Let's Encrypt Staging para testes. Os certificados Staging não são confiáveis para os navegadores de propósito. Essa é a finalidade: pode repetir a tentativa quantas vezes quiser sem consumir o limite de taxa de produção.

Você deve usar o servidor de email integrado?

O Cloudron disponibiliza uma pilha completa de email com caixas de correio IMAP, submissão, filtros sieve e assinatura DKIM (domainkeys identified mail). Ative-a por domínio, na secção Email do painel. O difícil é conseguir que as mensagens sejam entregues, e nenhuma dessas dificuldades é específica do Cloudron.

• A porta de saída 25 é bloqueada pela maioria dos provedores de VPS como medida antispam. Alguns desbloqueiam-na após um pedido ao suporte. Teste a partir do servidor com nc -zv aspmx.l.google.com 25 (instale netcat-openbsd se o comando não existir). O comando succeeded mostra o estado das portas, e uma porta bloqueada fica pendente até ocorrer um timeout.
• O registo PTR (DNS reverso) é configurado pelo provedor de VPS, não pelo provedor de DNS, e tem de corresponder ao hostname de email. As mensagens enviadas a partir de um endereço com um PTR genérico acabam nas pastas de spam.
• Os registos SPF, DKIM e DMARC são criados automaticamente num backend de DNS com API. Nos backends Wildcard ou Manual, tem de os adicionar manualmente. A ausência do registo DKIM faz com que nenhuma mensagem assinada possa ser validada.

Para a maioria dos utilizadores, a configuração mais prática é receber o email no Cloudron e enviar através de um relay, como SendGrid, Postmark, Mailgun ou Amazon SES, configurado na vista Email. O relay tem de permitir o envio como qualquer endereço do seu domínio. Caso contrário, as notificações das aplicações com remetentes diferentes são rejeitadas. Se o email for a principal razão para comprar o servidor, execute um servidor de email dedicado, como o Mailcow numa máquina própria, com a sua própria reputação de IP.

Se não utilizar o Cloudron Email, bloqueie as portas 25, 465, 587, 993 e 4190 na firewall do provedor. Faça isso nesse nível, e não no servidor, porque o Cloudron cria as regras iptables e espera geri-las. Isto é o oposto de um VPS simples, em que é você que gere as regras do ufw.

Configure o destino dos backups antes de precisar dele

Por padrão, os backups são gravados no sistema de ficheiros local em /var/backups, no mesmo disco que todos os restantes dados. A documentação é clara: "Manter os backups no mesmo disco físico que o servidor da plataforma é perigoso." Uma falha no disco elimina as aplicações e os backups ao mesmo tempo.

Abra Backups, depois Backup Sites, e configure outro destino logo no primeiro dia. O armazenamento de objetos compatível com S3 é a opção habitual (Backblaze B2, Wasabi, Cloudflare R2, DigitalOcean Spaces ou um bucket MinIO num segundo servidor). Também são suportados destinos SSHFS, NFS, CIFS e do sistema de ficheiros local.

Três definições determinam se vale a pena ter esse backup:

• Formato. tgz cria um arquivo comprimido por aplicação e volta a carregar o ficheiro completo em cada execução. rsync carrega apenas os ficheiros alterados. Isto é muito mais barato para uma instalação grande do Nextcloud, mas gera muito mais pedidos à API de armazenamento.
• Encriptação. AES-256 opcional que protege os conteúdos dos ficheiros e os nomes dos ficheiros. O Cloudron não guarda uma cópia da palavra-passe. Se a perder, ninguém poderá desencriptar os backups, incluindo você. Guarde-a num gestor de palavras-passe autoalojado antes de clicar em guardar.
• Retenção. É definida com quantidades, como 7 backups diários e 4 semanais. Uma retenção longa no armazenamento de objetos aumenta a fatura todos os meses. Escolha uma quantidade que esteja disposto a continuar a pagar.

Depois, teste um restauro. Instale uma aplicação pequena, restaure-a a partir do painel e confirme que regressa com os respetivos dados. Um backup que nunca foi restaurado é apenas uma suposição.

Limitações do plano gratuito

Em agosto de 2026, o plano gratuito está limitado a 2 aplicações instaladas. Tudo o resto está incluído: atualizações das aplicações, backups por aplicação, a firewall, o servidor de e-mail e o início de sessão único. A terceira aplicação é o ponto em que precisa de uma licença. Os planos pagos removem o limite de aplicações, e o plano superior acrescenta grupos e funções de utilizadores, um servidor de diretório e vários sites de backup. Os preços mudam, por isso consulte a página de preços do Cloudron em vez de usar um valor indicado num tutorial.

Uma licença abrange uma instalação do Cloudron, por isso 2 servidores pequenos custam o dobro de 1 servidor maior. Este modelo de preços leva a maioria das pessoas a usar um único VPS maior, o que contraria a recomendação habitual de distribuir os serviços por várias máquinas. Dimensione o servidor tendo isso em conta, porque dividir os serviços mais tarde significa pagar o dobro.

Quando algo falha

Comece pela verificação integrada. Ela analisa o DNS, os certificados, o disco, a memória e cada serviço, pela ordem, e indica qual teste falhou:

sudo cloudron-support --troubleshoot

Depois, use as ferramentas normais do systemd (gestor do sistema e dos serviços). systemctl status box mostra o estado do próprio serviço Cloudron, journalctl -u box -n 100 apresenta os logs recentes e journalctl -u docker abrange o runtime de contentores subjacente. Tudo o que falhou durante a instalação fica registado em /var/log/cloudron-setup.log.

Um dashboard que não carrega normalmente indica um problema de DNS ou da firewall do fornecedor, e não do Cloudron. Execute dig +short my.example.com no seu portátil e confirme se as portas 80 e 443 estão abertas na firewall de rede do fornecedor. Este é um controlo separado das regras do próprio servidor. Se estiver a começar de novo, o script recusa uma segunda execução com Error: Cloudron is already installed. To reinstall, start afresh, e reconstruir o servidor é a solução limpa.

Quando o Cloudron não é a opção adequada

O Cloudron é adequado quando pretende gerir aplicações, e não a infraestrutura. É pouco adequado quando pretende executar os seus próprios contentores da forma que escolher, porque controla o nginx, o Docker e a firewall, e substitui as configurações que colocar nesses componentes. Se o seu plano for manter uma pasta com ficheiros Compose, Traefik à frente das suas próprias stacks Docker Compose oferece o mesmo TLS automático e encaminhamento por subdomínio, sem uma plataforma sobreposta. Se ainda não escolheu uma solução, Cloudron, CasaOS e Coolify comparados apresenta-as lado a lado, e a lista mais ampla do que pode alojar autonomamente é um ponto de partida melhor do que um guia de instalação.

FAQ

Quanta RAM o Cloudron precisa numa VPS?

O script de configuração recusa-se a executar com menos de 941 MB e a documentação pede 2 GB, mas esse é o mínimo para a plataforma sem aplicações instaladas. O Cloudron executa o Docker, o nginx, o seu próprio serviço box, contentores de bases de dados e a stack de correio desde o primeiro arranque. Reserve 4 GB para duas aplicações e 16 GB para cerca de dez, e adicione um ficheiro de swap, porque o Cloudron atribui swap ilimitada às aplicações e um servidor sem swap transforma a pressão sobre a memória em reinícios.

Posso instalar o Cloudron no Debian ou num servidor que já execute Docker?

Nenhuma das opções funciona. O script verifica a versão e termina com Cloudron requires Ubuntu 20.04, 22.04, 24.04, por isso Debian, Rocky e Alpine estão excluídos. Também termina quando nginx, docker ou node já está presente, porque instala versões fixas de todos eles e escreve a configuração do nginx e as regras do iptables. Comece com uma imagem Ubuntu limpa numa VPS KVM.

Porque é que os subdomínios das minhas aplicações falham, mas o dashboard funciona?

Falta o registo DNS wildcard. A configuração cria ou exige um registo A para my.example.com, por isso o dashboard é resolvido, enquanto wiki.example.com devolve NXDOMAIN e o navegador informa que o site não foi encontrado. Adicione um registo A para *.example.com a apontar para o IP do servidor e confirme com dig +short wiki.example.com antes de instalar a aplicação.

Tenho de usar o servidor de correio do Cloudron?

Não. Pode desativar o correio de entrada e enviar através de um relay externo, como Postmark, Mailgun ou Amazon SES. Esta é a opção mais segura quando o fornecedor bloqueia a porta de saída 25 ou quando o endereço IP não tem reputação para envio de correio. Se não usar o Cloudron Email, feche as portas 25, 465, 587, 993 e 4190 na firewall do fornecedor, e não no servidor.

O que acontece quando atinjo o limite de duas aplicações do plano gratuito?

O dashboard bloqueia a terceira instalação e pede uma chave de licença. As aplicações que já estão em execução não são alteradas: continuam a receber atualizações, continuam a ser incluídas nas cópias de segurança e mantêm os respetivos certificados. Adicionar uma licença remove o limite sem reinstalar nada, por isso o plano gratuito é uma forma adequada de testar primeiro a plataforma num domínio real.