Instalar Flarum numa VPS com PHP e MariaDB

Instalar o Flarum numa VPS com PHP e MariaDB

Instale o Flarum numa VPS e terá um fórum que funciona 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, e 2 GB de RAM são o mínimo prático antes de adicionar backups ou um serviço de correio. O Discourse justifica esse consumo numa comunidade ativa com milhares de publicações por dia. Num fórum com algumas centenas de pessoas, é infraestrutura pela qual paga todos os meses sem nunca a utilizar. O Flarum integra-se numa stack PHP que talvez já esteja a utilizar, por isso uma VPS com 1 GB, nginx e MariaDB pode alojá-lo juntamente com os restantes serviços. Se a decisão ainda estiver em aberto, a comparação mais abrangente de software de fóruns autoalojado cobre as restantes opções.

Este guia fixa a instalação no Flarum 1.x, atualmente na série 1.8. Em agosto de 2026, o Flarum 2.0 ainda é um release candidate, por isso 1.8 é a versão a utilizar num fórum de que outras pessoas dependem. As extensões são mais importantes aqui do que a versão do core, e a maioria dos autores de extensões ainda não migrou para a 2.0.

O que o Flarum 1.8 requer 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, pelo que os pacotes da distribuição satisfazem ambos os requisitos sem um repositório de terceiros. As extensões PHP necessárias para o Flarum são curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer e zip. Também precisa de acesso à shell, porque o Composer é obrigatório neste caso: cada extensão do Flarum é um pacote Composer e não existe outra forma de adicionar uma extensão sem executar o Composer.

O Flarum é uma aplicação PHP normal. 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.

Instalar 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 --version

Os 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 são compiladas no PHP 8.3 do Ubuntu. Por isso, não existe um pacote para instalar para essas extensões. grep deve apresentar seis linhas e composer --version deve indicar uma versão 2.x. Vale a pena corrigir agora qualquer extensão em falta, porque o Composer recusa instalar o Flarum sem ela e identifica a extensão no erro:

  Problem 1
    - flarum/core[v1.8.0, ..., v1.8.17] require ext-gd * -> it is missing from your system.
      Install or enable PHP's gd extension.

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 mariadb

CREATE 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 do sistema que seja proprietário do código. Executar o Composer como root deixa ficheiros pertencentes a root em vendor/ e storage/. Depois, 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 flarum

Esse último comando abre uma shell como o utilizador flarum, em /srv/flarum. Todos os comandos até ao fim do guia são executados nesse contexto, 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, que é o comportamento pretendido enquanto a 2.0 for uma release candidate. O Composer descarrega o esqueleto, resolve flarum/core e as respetivas dependências, e deixa os ficheiros 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 erro do PHP, indica o OOM killer do kernel. Pode confirmar isso com dmesg | tail. Nesse caso, a máquina ficou realmente sem RAM, portanto adicione swap. Aumentar o limite do PHP piora a situação, 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] = 17M

sudo systemctl restart php8.3-fpm
ls -l /run/php/php8.3-fpm-flarum.sock

O 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 nginx

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

O 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 info

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

Uma 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:clear

Depois, 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:clear

O 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:clear

Leia a saída em vez de assumir que a operação funcionou. O caso importante é 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 indicou que não funcionará. Encontre o pacote responsável.

composer why-not flarum/core 1.8.17

A 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 aguardar que o autor publique uma versão compatível ou remover a extensão e deixar de a utilizar. Esse é o custo do modelo do Composer. É importante compreendê-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. Mantenha a lista suficientemente curta para que consiga analisá-la.

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 flarum

Em 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 consultar o fórum. 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 terminado pelo OOM 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 bloco de servidor do nginx não tem include /srv/flarum/.nginx.conf;. O Flarum processa no PHP URLs como /d/1-hello-world, 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 o próprio 404 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 todos os estilos depois de ativar HTTPS?

O Flarum guarda o URL base em config.php, obtido a partir do endereço utilizado 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 esses recursos como conteúdo misto numa página HTTPS, deixando apenas texto sem estilos. Edite a chave url em /srv/flarum/config.php para usar o endereço https:// e execute php flarum cache:clear como o utilizador 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 Ubuntu VPS. 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 clique em Enviar email de teste. Se o log mostrar 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?

Instale o 1.8. Em agosto de 2026, o Flarum 2.0 é uma release candidate. Além disso, muitas extensões ainda declaram uma restrição flarum/core que termina na versão 1.x. Instalar o 2.0 atualmente significa executar um fórum cujas extensões não podem ser atualizadas em conjunto. Essa é precisamente a falha que composer why-not existe para diagnosticar. Fixe a versão com flarum/flarum:^1.8.0 e volte a avaliar quando as extensões de que depende tiverem publicado releases para 2.0.