Instalar Flarum numa VPS com PHP e MariaDB
Veja como instalar o Flarum 1.8 numa VPS com PHP, Composer e MariaDB, servir apenas /public via TLS e corrigir falhas de correio e upgrades de extensões.
Instalar o Flarum numa VPS com PHP e MariaDB
Ao instalar o Flarum numa VPS, obtém um fórum executado com PHP e MariaDB, sem Docker, sem Ruby e sem um executor de tarefas separado. Esse é o motivo para o escolher. Instalar o Discourse numa VPS significa manter uma stack Docker com Ruby, PostgreSQL, Redis e um worker em segundo plano. O guia de instalação do Discourse recomenda 2 GB de RAM (1 GB funciona apenas com swap), antes de adicionar backups ou um serviço de correio. O Discourse justifica essa utilização de recursos numa comunidade ativa com milhares de publicações por dia. Num fórum com algumas centenas de pessoas, é uma infraestrutura pela qual paga todos os meses sem nunca utilizar a capacidade disponível. O Flarum integra-se numa stack PHP que talvez já esteja a executar. Assim, uma VPS com 1 GB, nginx e MariaDB pode alojá-lo juntamente com os restantes serviços. Se a escolha ainda estiver em aberto, a comparação mais abrangente de software de fóruns self-hosted cobre as restantes opções.
Este guia fixa a instalação no Flarum 1.x, atualmente na série 1.8. O Flarum 2.0.0 tornou-se a versão estável em 9 October 2026. No entanto, em 12 October 2026, o próprio guia de atualização do Flarum indica que muitas extensões apenas tinham lançado versões beta para a versão 2.0, e que a linha 1.x continuava a receber correções para bugs críticos e problemas de segurança. As extensões são mais importantes neste caso do que a versão do core. Por isso, a versão 1.8 continua a ser a opção mais segura para um fórum que dependa delas. Se não precisar de extensões de terceiros, a versão 2.0 é a versão atual. Requer PHP 8.3 ou posterior, disponibilizado pelo Ubuntu 24.04, e a documentação do Flarum instala-a com composer create-project flarum/flarum:^2.0.0 .. Os comandos abaixo foram escritos para a versão 1.8.
O que o Flarum 1.8 precisa no servidor
Os requisitos documentados do Flarum são PHP 7.3 ou mais recente, MySQL 5.6+ ou MariaDB 10.0.5+, e nginx ou Apache com mod_rewrite. O Ubuntu 24.04 inclui PHP 8.3 e MariaDB 10.11, portanto os pacotes da distribuição satisfazem ambos os requisitos sem um repositório de terceiros. O Flarum 2.0 eleva esses requisitos para PHP 8.3+, MySQL 5.7+ / 8.0.30+ ou MariaDB 10.3+, que os mesmos pacotes do Ubuntu também satisfazem. As extensões PHP exigidas pelo Flarum são curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer e zip. Também precisa de acesso à shell, porque o Composer não é opcional neste caso: todas as extensões do Flarum são pacotes Composer e não é possível adicionar uma sem executar o Composer.
O Flarum é uma aplicação PHP comum. Se já executa uma stack LAMP no Ubuntu 24.04, a maior parte das duas secções seguintes já está instalada e pode avançar para a base de dados.
Instale o PHP e as extensões exigidas pelo Flarum
sudo apt update
sudo apt install -y nginx mariadb-server composer
sudo apt install -y php8.3-fpm php8.3-cli php8.3-curl php8.3-gd php8.3-mbstring php8.3-mysql php8.3-xml php8.3-zip
php -m | grep -E 'curl|dom|gd|mbstring|pdo_mysql|zip'
composer --versionOs nomes dos pacotes não correspondem exatamente à lista do Flarum. A extensão dom está incluída em php8.3-xml, e fileinfo, json, openssl e tokenizer já vêm integradas no PHP 8.3 do Ubuntu ou são fornecidas por php8.3-common, que os pacotes acima instalam como dependência. Por isso, não é necessário instalar nada adicional para essas extensões. O comando grep deve mostrar sete linhas: as seis extensões e random, um módulo que o PHP 8.3 carrega sempre e cujo nome contém dom. composer --version deve indicar uma versão 2.x. Vale a pena corrigir agora qualquer extensão em falta. Se deixar de instalar php8.3-xml, por exemplo, o Composer recusa-se a instalar o Flarum, porque uma das dependências declara ext-dom. A mensagem de erro identifica a extensão. A linha relevante termina assim:
require ext-dom * -> it is missing from your system. Install or enable PHP's dom extension.No entanto, o Composer não verifica todas as extensões da lista do Flarum. A biblioteca de imagens utilizada pelo Flarum 1.8 apenas recomenda gd. Por isso, um servidor sem essa extensão conclui a instalação sem erros e só falha mais tarde, quando o Flarum precisa de processar um avatar ou logótipo carregado.
Confirme que o PHP da linha de comandos e o gestor de processos FastCGI (PHP-FPM) usam a mesma versão. O Composer é executado pelo binário da linha de comandos, enquanto o fórum é executado pelo FPM. Por isso, php -v e sudo php-fpm8.3 -v têm de coincidir. As versões podem divergir numa máquina que acumulou várias versões do PHP provenientes de um repositório de terceiros. Nesse caso, uma extensão instalada para uma versão fica invisível para a outra.
Crie o banco de dados e um usuário dedicado do banco de dados
sudo mariadb-secure-installation
sudo mariadbCREATE DATABASE flarum CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'flarum'@'localhost' IDENTIFIED BY 'use-a-long-random-password';
GRANT ALL PRIVILEGES ON flarum.* TO 'flarum'@'localhost';
FLUSH PRIVILEGES;
EXIT;Dê ao Flarum o seu próprio usuário do banco de dados, em vez de root. A concessão de permissões abrange flarum.* e nada mais. Assim, uma vulnerabilidade de injeção SQL numa extensão que não escreveu não pode ler os seus outros bancos de dados. O conjunto de caracteres também é importante: utf8mb4 armazena corretamente emoji e scripts não latinos, enquanto o antigo utf8 do MySQL usa uma codificação de três bytes que trunca uma publicação no primeiro caractere de quatro bytes. Confirme que o usuário funciona antes de continuar.
mariadb -u flarum -p flarum -e 'SELECT DATABASE();'Isso deve imprimir flarum. ERROR 1045 (28000): Access denied for user 'flarum'@'localhost' significa que a senha não corresponde ou que o usuário foi criado para um host diferente de localhost.
Instalar o Flarum numa VPS com Composer, fixado na versão 1.8
Primeiro, crie um utilizador de sistema que seja proprietário do código. Executar o Composer como root deixa ficheiros pertencentes a root em vendor/ e storage/. Mais tarde, o PHP não consegue escrever na própria cache, e o fórum responde a todos os pedidos com um erro 500.
sudo useradd --system --home-dir /srv/flarum --shell /bin/bash flarum
sudo install -d -o flarum -g flarum -m 755 /srv/flarum
sudo -iu flarumO último comando abre uma shell como o utilizador flarum, em /srv/flarum. Todos os comandos desde este ponto até ao fim do guia são executados com esse utilizador, exceto quando começam por sudo.
composer create-project flarum/flarum:^1.8.0 .A restrição ^1.8.0 fixa a versão. Aceita versões de correção 1.8.x e recusa a versão 2.0. Isto é importante agora que 2.0.0 é a versão estável: sem a restrição, composer create-project instala a versão 2.0. O Composer descarrega o esqueleto, resolve flarum/core e as respetivas dependências, e deixa disponíveis public/, storage/, vendor/, composer.json e um script de linha de comandos flarum.
Numa VPS pequena, é nesta etapa que surgem problemas, e duas falhas diferentes podem parecer iguais. PHP Fatal error: Allowed memory size of 134217728 bytes exhausted é o memory_limit do próprio PHP. Colocar COMPOSER_MEMORY_LIMIT=-1 antes do comando remove esse limite durante uma execução. Um Killed isolado numa linha própria, sem uma mensagem de erro do PHP, indica que o kernel terminou o processo por falta de memória. Pode confirmar isso com dmesg | tail. Nesse caso, a máquina ficou realmente sem RAM, por isso adicione swap. Aumentar o limite de memória do PHP agrava o problema, porque o PHP passa a pedir ainda mais memória antes de o kernel intervir.
Por que apenas /public deve ficar exposto na web
A raiz do projeto contém config.php com a palavra-passe da base de dados em texto simples, vendor/ com todas as dependências e storage/ com logs e sessões em cache. Nada disso deve ficar disponível na Internet pública. O Flarum mantém tudo o que é acessível pela web num único subdiretório, public/, que contém index.php, uma pasta assets/ e pouco mais. Aponte a raiz do servidor web para /srv/flarum/public. Assim, o restante da árvore fica inacessível por HTTP por construção, e não por uma regra de que tenha de se lembrar.
Aponte a raiz para /srv/flarum e o risco é real. Pedir /config.php não devolve nada útil, porque o PHP executa o ficheiro e ele devolve apenas um array. Já /storage/logs/flarum.log expõe os seus stack traces e erros de base de dados, e /composer.lock informa a versão exata de cada pacote utilizado, fornecendo uma lista de vulnerabilidades conhecidas para explorar.
Dê ao PHP-FPM o seu próprio pool
O Flarum precisa de acesso de escrita a três caminhos: à raiz do projeto, para o instalador poder criar config.php; a storage/, para logs e cache; e a assets/, para avatares e logótipos carregados. Os ficheiros pertencem ao utilizador flarum, por isso a solução correta é um pool PHP-FPM executado como flarum. O nginx continua a ser executado como www-data e apenas lê.
Escreva /etc/php/8.3/fpm/pool.d/flarum.conf:
[flarum]
user = flarum
group = flarum
listen = /run/php/php8.3-fpm-flarum.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
pm = ondemand
pm.max_children = 10
pm.process_idle_timeout = 30s
php_admin_value[memory_limit] = 256M
php_admin_value[upload_max_filesize] = 16M
php_admin_value[post_max_size] = 17Msudo systemctl restart php8.3-fpm
ls -l /run/php/php8.3-fpm-flarum.sockO socket deve ser apresentado como srw-rw---- 1 www-data www-data. O processo principal é executado como root e cria o socket. Por isso, pode atribuir-lhe a propriedade de www-data, enquanto os workers são executados como flarum. Se o socket não estiver presente, sudo journalctl -u php8.3-fpm -n 30 apresenta a linha FPM rejected. pm = ondemand inicia processos worker apenas quando chega um pedido. Assim, um fórum pouco movimentado consome quase nenhuma memória entre visitas.
O bloco server do nginx
O Flarum inclui um fragmento do nginx na raiz do projeto chamado .nginx.conf. Esse fragmento contém a regra de reescrita, os cabeçalhos de cache e as definições de compressão. Inclua-o em vez de o copiar. Assim, uma atualização do Flarum que altere o fragmento chega ao seu servidor sem ser necessário editar nada.
server {
listen 80;
listen [::]:80;
server_name forum.example.com;
root /srv/flarum/public;
index index.php;
client_max_body_size 16M;
include /srv/flarum/.nginx.conf;
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.3-fpm-flarum.sock;
}
}Guarde isso como /etc/nginx/sites-available/flarum e ative-o.
sudo ln -s /etc/nginx/sites-available/flarum /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginxnginx -t deve responder a syntax is ok e test is successful. A linha include é a que muitas pessoas omitem. Quando isso acontece, há um sintoma muito específico: a página inicial carrega corretamente e todos os links das discussões devolvem 404 do nginx. O Flarum encaminha um URL como /d/1-hello-world dentro do PHP. Esse caminho não corresponde a um ficheiro no disco. Sem a regra try_files $uri $uri/ /index.php?$query_string do fragmento, o nginx procura um diretório chamado d, não o encontra e devolve 404 antes de o PHP ser sequer chamado. O Apache obtém o mesmo encaminhamento a partir do ficheiro .htaccess que já se encontra em public/. Essa configuração só tem efeito se o bloco <Directory> correspondente definir AllowOverride All.
Adicione o TLS antes de executar o instalador
Configure o certificado agora, não depois. O Flarum grava a sua URL base em config.php durante a instalação e obtém essa URL a partir do endereço no navegador. Instale através de http:// e todas as URLs de recursos que o Flarum gerar depois começarão por http://. Quando adicionar TLS (transport layer security), o navegador bloqueará esses pedidos como conteúdo misto e o fórum será carregado como texto sem estilos e sem JavaScript. Primeiro, siga a configuração do certbot para Let's Encrypt no nginx, confirme que https://forum.example.com apresenta uma página e depois volte aqui.
Se já instalou através de HTTP simples, a correção requer uma linha. Edite /srv/flarum/config.php para que a chave url tenha o valor 'url' => 'https://forum.example.com', e depois execute php flarum cache:clear como o utilizador flarum.
Execute o instalador e restrinja o acesso a config.php
Abra https://forum.example.com num navegador. O instalador web do Flarum solicita o nome da base de dados, o utilizador e a palavra-passe da base de dados que criou, o título do fórum e a sua conta de administrador. O instalador grava config.php e cria as tabelas. Quando terminar, restrinja o ficheiro que agora contém a palavra-passe da base de dados.
sudo chmod 640 /srv/flarum/config.phpO ficheiro continua legível e gravável por flarum, que é o utilizador com que o FPM é executado, e fica inacessível para todas as outras contas do servidor. Depois, verifique a instalação a partir da shell.
php flarum infoEste comando apresenta a versão do core, a versão do PHP, as extensões ativadas, o driver de correio e os caminhos utilizados. É o primeiro comando a executar quando algo não funciona corretamente e a primeira informação que alguém que o está a ajudar lhe irá pedir.
Por que os emails de registo e reposição da palavra-passe falham silenciosamente
Esta secção determina se o seu fórum sobrevive à primeira semana. Os dois primeiros emails que um fórum novo envia são a confirmação do registo e a reposição da palavra-passe. Ambos são enviados no momento exato em que uma pessoa desconhecida decide se a sua comunidade é real. Ambos podem falhar silenciosamente. A pessoa que nunca recebeu o email não consegue avisá-lo, e nada no painel de administração fica assinalado a vermelho.
O Flarum tem quatro drivers de email, definidos em Administration e depois Email: smtp, mail, mailgun e log. Escolha smtp e aponte-o para um serviço de email que entregue realmente as mensagens. O driver mail entrega a mensagem a um binário local do sendmail. Esse binário não existe num VPS Ubuntu acabado de instalar, por isso a mensagem não chega a lado nenhum e nenhum erro é apresentado. O driver log escreve o corpo da mensagem em storage/logs/ e não envia nada, porque existe para desenvolvimento.
Guarde as definições e prima o botão Send Test Mail na mesma página. Esse botão é o único mecanismo de confirmação disponível, por isso use-o antes de convidar alguém. Se a mensagem não chegar, consulte o log.
tail -n 50 /srv/flarum/storage/logs/flarum.logUma ligação recusada, um login rejeitado e uma falha na negociação TLS ficam registados nesse log, juntamente com o host e a porta utilizados. Uma linha com Connection could not be established with host smtp.example.com significa que a porta está bloqueada ou incorreta. A causa habitual é o bloqueio, por predefinição, das ligações de saída na porta 25 pelo fornecedor. A porta 587 com o campo de encriptação definido como tls é a combinação que funciona com quase todos os serviços de email.
Quando o email está avariado, um visitante que se regista vê o aviso genérico de falha do Flarum, Oops! Something went wrong. Please reload the page and try again., porque o pedido falha durante o envio da confirmação. Em qualquer dos casos, essa pessoa não consegue entrar e provavelmente não o contactará sobre o problema.
Fazer com que o email seja aceite é um problema separado de conseguir enviá-lo. As mensagens enviadas a partir do endereço de um VPS sem registos SPF ou DKIM publicados para o seu domínio chegam à pasta de spam ou são descartadas sem qualquer mensagem de devolução. Assim, o log mostra um envio bem-sucedido, mas o destinatário continua sem ver a mensagem. Enviar emails de forma fiável a partir de aplicações alojadas autonomamente explica quais os registos DNS a publicar e quais os serviços de relay que vale a pena utilizar.
Extensões são pacotes Composer, por isso as atualizações são feitas por comando
No Flarum, uma extensão é um pacote Composer. Não existe botão de upload nem ficheiro zip para colocar numa pasta. Esta é uma decisão de design deliberada: as versões são resolvidas entre si, o conjunto exato fica registado em composer.lock e uma extensão que dependa de uma biblioteca PHP instala essa biblioteca corretamente. O custo é que adicionar uma extensão exige três comandos executados pelo utilizador flarum.
composer require 'fof/upload:*'
php flarum migrate
php flarum cache:clearDepois, ative-a em Administration e Extensions. Cada comando executa uma tarefa distinta. composer require coloca o código no disco. php flarum migrate executa as migrações de base de dados incluídas na extensão, que é o mecanismo usado para criar as respetivas tabelas. php flarum cache:clear recompila os bundles de JavaScript e CSS que o browser carrega. Ignorar o último comando causa a confusão habitual: a extensão aparece na lista, o interruptor está ativado e nada muda no browser, mesmo depois de recarregar a página várias vezes.
A remoção de uma extensão segue o processo inverso. Desative-a primeiro no painel de administração e remova depois o pacote. O Flarum mantém deliberadamente as tabelas da extensão, para que uma reativação posterior não provoque perda de dados. Para as remover também, reverta as respetivas migrações antes de remover o código.
php flarum migrate:reset --extension fof-upload
composer remove fof/upload
php flarum cache:clearO id da extensão nesse comando é o nome do pacote com a barra substituída por um hífen. Se preferir clicar em vez de escrever, composer require 'flarum/extension-manager:*' adiciona uma página de administração oficial que encapsula o Composer. Executa as mesmas operações que o utilizador web, precisa da mesma memória e das mesmas permissões de escrita e falha pelas mesmas razões. Por isso, a linha de comandos continua a ser o caminho mais fiável quando ocorre um problema.
Por que composer update se recusa a atualizar o Flarum
Atualizar o Flarum e todas as extensões requer um comando do Composer seguido de dois comandos do Flarum. Faça primeiro uma cópia de segurança da base de dados.
composer update --prefer-dist --no-plugins --no-dev -a --with-all-dependencies
php flarum migrate
php flarum cache:clearLeia a saída em vez de assumir que a atualização funcionou. O caso relevante ocorre quando o Composer se recusa a fazer qualquer alteração:
Your requirements could not be resolved to an installable set of packages.Essa mensagem significa que uma extensão instalada declara uma restrição flarum/core que exclui a versão para a qual pretende atualizar. O Composer não viola a restrição. Por isso, mantém toda a instalação na versão antiga, em vez de montar uma combinação que o autor da extensão declarou que não funcionará. Identifique o pacote responsável.
composer why-not flarum/core 1.8.20A saída lista todos os pacotes que bloqueiam essa versão e a restrição declarada por cada um. A partir daí, as opções são esperar que o autor publique uma versão compatível ou remover a extensão e ficar sem ela. Este é o custo do modelo do Composer. É importante entendê-lo antes de instalar quinze extensões num fórum de que dependem outras pessoas. Prefira extensões que tenham lançado uma versão recentemente e mantenha a lista suficientemente curta para conseguir analisá-la.
Estes comandos mantêm o sistema dentro da série 1.x. Passar de 1.8 para 2.0 é uma atualização principal com um guia próprio na documentação do Flarum. Ela requer PHP 8.3, alterações em composer.json, uma alteração de driver em config.php nas instalações com MariaDB e a remoção de qualquer extensão que não tenha uma versão 2.0.
O que fazer backup
Faça backup do banco de dados e do diretório do projeto. Todo o resto pode ser recriado.
mariadb-dump -u flarum -p --single-transaction flarum > flarum-$(date +%F).sql
sudo tar czf flarum-files.tgz -C /srv flarumEm sistemas mais antigos, mariadb-dump chama-se mysqldump; no Ubuntu 24.04, os dois nomes funcionam. O banco de dados contém todas as publicações, todos os utilizadores e todas as definições. O diretório do projeto contém config.php, composer.json (que é o registo real das extensões em execução) e assets/, com os avatares e logótipos carregados. Pode ignorar vendor/, porque composer install o recria a partir de composer.lock, e storage/ regenera-se automaticamente. Copie os dois ficheiros para fora do servidor, porque um backup armazenado na máquina que protege não é um backup. A restauração requer uma instalação nova do Flarum com a mesma versão, composer install, os ficheiros guardados novamente no local correto e o ficheiro SQL carregado.
FAQ
O Flarum pode ser executado num VPS com 1 GB?
Sim, para uma comunidade pequena. Em funcionamento normal, o Flarum é composto pelo PHP-FPM a responder aos pedidos e pelo MariaDB. Com pm = ondemand, os workers PHP só existem enquanto alguém está a ler. O pico ocorre durante a instalação: composer create-project resolve todo o grafo de dependências em memória e é o passo com maior probabilidade de ser interrompido pelo out-of-memory killer. Crie um ficheiro de swap antes da instalação ou execute o Composer uma vez numa máquina maior e copie a árvore de ficheiros.
Porque é que os links das discussões devolvem 404 quando a página inicial funciona?
O seu server block do nginx não tem include /srv/flarum/.nginx.conf;. O Flarum processa URLs como /d/1-hello-world dentro do PHP, e esse caminho não corresponde a um ficheiro no disco. Sem a regra try_files $uri $uri/ /index.php?$query_string do snippet, o nginx procura um diretório chamado d, falha e devolve 404 diretamente, sem nunca chamar o PHP. No Apache, o mesmo encaminhamento é fornecido por public/.htaccess, que é ignorado a menos que o bloco <Directory> defina AllowOverride All.
Porque é que o meu fórum perdeu toda a formatação depois de ativar HTTPS?
O Flarum guarda o URL base em config.php, obtido a partir do endereço usado durante a execução do instalador. Se instalou através de HTTP simples, o Flarum continua a gerar URLs de recursos http://. O navegador bloqueia-os como mixed content numa página HTTPS, deixando apenas texto sem formatação. Edite a chave url em /srv/flarum/config.php para o endereço https:// e execute php flarum cache:clear com o utilizador que é proprietário dos ficheiros.
Porque é que ninguém recebe o email de confirmação do registo?
Verifique primeiro o driver de email. O driver mail precisa de um binário sendmail local, que não existe numa instalação nova de um VPS Ubuntu. O driver log escreve em storage/logs/ e não envia nada. Mude para smtp, use a porta 587 com a encriptação definida como tls, porque a maioria dos fornecedores bloqueia a porta de saída 25, e prima Send Test Mail. Se o log indicar um envio bem-sucedido e o email continuar sem chegar, o problema está na entregabilidade, não na configuração. Nesse caso, publique registos SPF e DKIM para o seu domínio de envio.
Devo instalar o Flarum 1.8 ou 2.0?
Por agora, instale a versão 1.8 se o seu fórum depender de extensões de terceiros. O Flarum 2.0.0 tornou-se a release estável em 9 October 2026, mas, em 12 October 2026, o guia de atualização do Flarum indica que muitas extensões apenas tinham lançado versões beta para 2.0. Além disso, qualquer extensão sem uma release para 2.0 continua a declarar uma restrição flarum/core que termina na versão 1.x. Instalar a versão 2.0 hoje faz com que o Composer recuse imediatamente essas extensões. Este é o mesmo conflito de restrições que composer why-not existe para diagnosticar. Fixe a versão com flarum/flarum:^1.8.0 e atualize para 2.0 através do guia de atualização do Flarum quando as extensões de que depende tiverem releases estáveis para 2.0. Tenha em conta que a versão 1.x recebe agora apenas correções para erros críticos e problemas de segurança. Um fórum que não precise de extensões de terceiros pode começar hoje na versão 2.0 com flarum/flarum:^2.0.0.