Como instalar o FreshRSS no Ubuntu com Apache e MariaDB

O que está a construir

Um leitor RSS self-hosted é um leitor de feeds que é executado num servidor que controla, para que ninguém o possa desligar nem alterar o conteúdo apresentado. Este guia instala o FreshRSS num VPS com Ubuntu 24.04: Apache à frente, PHP por trás, MariaDB para armazenamento e uma tarefa cron que obtém novos artigos. RSS (really simple syndication) é o formato de ficheiro que um site publica para que o software possa ler os seus artigos. FreshRSS é a aplicação PHP que recolhe esses ficheiros, guarda os artigos e disponibiliza uma interface web, além de uma API (application programming interface) usada pelas aplicações móveis.

A instalação é simples: extrair uma release, criar uma base de dados, escrever um virtual host, executar o instalador da linha de comandos e criar a conta com cli/create-user.php. A maior parte do trabalho abaixo trata dos problemas que surgem depois, sobretudo a tarefa de atualização, as barras codificadas nos caminhos da API móvel e a propriedade dos ficheiros.

FreshRSS 1.30.4, publicada em October 21, 2026, é a release atual em October 29, 2026 e requer PHP 8.1 ou mais recente. Ubuntu 24.04 inclui PHP 8.3, por isso os pacotes da distribuição são suficientes e não precisa de um repositório PHP de terceiros.

Comece por uma stack LAMP funcional

O FreshRSS é uma aplicação PHP comum, por isso precisa da mesma base que qualquer outra aplicação. Se ainda não preparou essa base, siga primeiro a configuração da stack LAMP para Ubuntu 24.04 e depois volte aqui. A versão resumida:

sudo apt update
sudo apt install -y apache2 mariadb-server php libapache2-mod-php
sudo systemctl enable --now apache2 mariadb

systemctl status apache2 deve apresentar active (running). Se o Apache não arrancar, a causa habitual é outro processo já estar a usar a porta 80; sudo ss -ltnp | grep :80 identifica esse processo.

As extensões PHP necessárias ao FreshRSS

O FreshRSS considera libxml, cURL, JSON, PDO_MySQL, PCRE e ctype obrigatórias. Também requer mbstring, iconv, Zlib e ZipArchive, além de GMP num sistema de 32 bits. No Ubuntu, estas extensões são instaladas como pacotes da distribuição:

sudo apt install -y php-curl php-mbstring php-xml php-zip php-mysql php-intl php-gmp
sudo systemctl restart apache2

Verifique o que o PHP carregou efetivamente com php -m. Uma extensão em falta não impede o instalador de iniciar. O instalador só falha no ecrã de requisitos, com uma linha vermelha que identifica a extensão. Esse é um local confuso para descobrir o problema, por isso confirme agora. Reiniciar o Apache é importante porque libapache2-mod-php mantém o PHP dentro do processo do Apache. Por isso, uma extensão instalada recentemente não fica disponível para o servidor Web até este ser reiniciado.

Baixe o release

Instale o FreshRSS fora da raiz web padrão e configure o Apache para apontar para ele. Manter o diretório da aplicação separado da raiz de documentos garante que apenas a pasta pública fique acessível por HTTP.

cd /tmp
curl -fsSLO https://github.com/FreshRSS/FreshRSS/archive/refs/tags/1.30.4.tar.gz
tar xzf 1.30.4.tar.gz
sudo mv FreshRSS-1.30.4 /srv/freshrss

Agora, as permissões, que a documentação do FreshRSS define de forma rigorosa: o utilizador do servidor web é o proprietário de toda a árvore, o grupo pode ler todos os ficheiros e pode escrever em ./data/.

sudo chown -R www-data:www-data /srv/freshrss
sudo chmod -R g+r /srv/freshrss
sudo chmod -R g+w /srv/freshrss/data

Se ignorar este passo, o instalador falha ao escrever a configuração, porque o PHP é executado como www-data e www-data não pode escrever num diretório pertencente a root.

Criar a base de dados

O FreshRSS é compatível com SQLite, MariaDB, MySQL e PostgreSQL. O SQLite requer a extensão php-sqlite3, mas não exige a configuração de um servidor de base de dados e armazena os dados de cada utilizador num ficheiro data/users/_user_/db.sqlite separado. Adicionar utilizadores não coloca as respetivas escritas num único ficheiro SQLite partilhado; este guia utiliza MariaDB como parte da stack LAMP.

sudo mariadb -e "CREATE DATABASE freshrss CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mariadb -e "CREATE USER 'freshrss'@'localhost' IDENTIFIED BY 'ReplaceThisPassword';"
sudo mariadb -e "GRANT ALL PRIVILEGES ON freshrss.* TO 'freshrss'@'localhost';"
sudo mariadb -e "FLUSH PRIVILEGES;"

Utilize utf8mb4 e não utf8. Os feeds podem conter emoji e scripts não latinos, e a codificação antiga de três bytes utf8 não consegue armazenar caracteres de quatro bytes. Os caracteres não suportados causam um erro no modo estrito predefinido do MariaDB; o truncamento depende do modo SQL e de opções da instrução, como IGNORE.

O host virtual do Apache

O diretório público é p/, não o nível superior da árvore. Tudo o resto, incluindo o ficheiro de configuração que contém a palavra-passe da base de dados, fica acima da raiz dos documentos, onde o Apache nunca o irá servir.

<VirtualHost *:80>
	ServerName rss.example.com
	DocumentRoot /srv/freshrss/p/

	<Directory /srv/freshrss/p>
		AllowOverride AuthConfig FileInfo Indexes Limit
		Require all granted
	</Directory>

	ErrorLog ${APACHE_LOG_DIR}/freshrss_error.log
	CustomLog ${APACHE_LOG_DIR}/freshrss_access.log combined

	AllowEncodedSlashes On
</VirtualHost>

Guarde esse conteúdo como /etc/apache2/sites-available/freshrss.conf e ative-o:

sudo a2enmod rewrite
sudo a2ensite freshrss
sudo a2dissite 000-default
sudo apache2ctl configtest
sudo systemctl reload apache2

configtest deve apresentar Syntax OK. AllowEncodedSlashes On parece opcional, mas não é: a API do Google Reader envia identificadores de feeds que contêm %2F e, sem esta diretiva, o Apache rejeita-os. Por isso, as aplicações móveis não conseguem sincronizar, embora a interface web funcione corretamente.

Adicione HTTPS antes de iniciar sessão

Está prestes a introduzir uma palavra-passe neste site, por isso obtenha primeiro um certificado. Aponte um registo A para o servidor, siga a configuração do Certbot para Apache no Ubuntu e execute sudo certbot --apache -d rss.example.com. O Certbot reescreve o virtual host da porta 443 e adiciona o redirecionamento. Confirme com curl -I https://rss.example.com/, que deve devolver um 200 ou um redirecionamento para a página de início de sessão.

Execute o instalador na linha de comandos

O FreshRSS tem um instalador no navegador, mas a versão da linha de comandos pode ser repetida e deixa um registo exato das opções escolhidas.

sudo -u www-data php /srv/freshrss/cli/do-install.php \
  --default-user admin --auth-type form --environment production \
  --base-url https://rss.example.com --language en --api-enabled \
  --db-type mysql --db-host localhost --db-user freshrss \
  --db-password 'ReplaceThisPassword' --db-base freshrss
sudo -u www-data php /srv/freshrss/cli/create-user.php \
  --user admin --password 'a-long-passphrase' --api-password 'a-different-passphrase'

Execute ambos como www-data. Executá-los como root cria ficheiros de configuração pertencentes a root, e a interface web deixa de conseguir guardar definições posteriormente. --environment production também é importante, porque a definição de desenvolvimento apresenta avisos do PHP na página.

Carregue https://rss.example.com/ e inicie sessão como admin.

Por que os feeds não são atualizados automaticamente

Nenhum processo consulta os seus feeds até ser configurado para isso. Abrir o FreshRSS não agenda a obtenção dos feeds. Sem um agendador, use a ligação de atualização no menu de navegação para obter os artigos manualmente. A solução é o script que o projeto fornece para esta finalidade, app/actualize_script.php, executado pelo cron.

sudo crontab -u www-data -e

Adicione uma linha:

*/20 * * * * php /srv/freshrss/app/actualize_script.php > /tmp/FreshRSS.log 2>&1

Vinte minutos é um intervalo adequado, mas o intervalo de atualização de cada feed continua a aplicar-se: o padrão é uma hora, e os feeds individuais aceitam intervalos a partir de quinze minutos. Execute-o manualmente uma vez:

sudo -u www-data php /srv/freshrss/app/actualize_script.php

Uma saída normal informa sobre a execução da atualização e termina sem um erro de PHP. Os nomes dos feeds aparecem quando são adicionados ou atualizados artigos. Se não apresentar qualquer saída, verifique a saída de erros do PHP e os logs do FreshRSS. O silêncio, por si só, não identifica o utilizador do cron como a causa. Um erro de permissões em data/ exige a verificação do proprietário e das permissões de escrita.

Adicione os primeiros feeds

Use o botão de adição no canto superior esquerdo da interface, cole o endereço de um site e o FreshRSS deteta a ligação do feed. A maioria dos sites continua a publicar um, mesmo quando não o anuncia, normalmente em /feed, /rss ou /atom.xml. As categorias são pastas, e mover um feed entre elas é uma operação de arrastar.

Se vier de outro leitor, exporte um ficheiro OPML nesse leitor e importe-o na página de gestão das subscrições. OPML (outline processor markup language) é o formato padrão para listas de feeds, e todos os leitores que vale a pena deixar suportam-no. Uma importação grande é lenta na primeira atualização porque cada feed é obtido uma vez. Por isso, aguarde a primeira execução do cron antes de avaliar a velocidade.

Leia no telemóvel

O FreshRSS disponibiliza a API do Google Reader, que é compatível com muitas aplicações de RSS. Duas condições têm de ser cumpridas. Nas definições de autenticação, a opção "Allow API access" tem de estar ativa; a flag --api-enabled acima já a ativou. No seu perfil, o campo da palavra-passe da API tem de conter um valor. Essa palavra-passe é deliberadamente separada da palavra-passe de início de sessão, porque é mais fácil perder um telemóvel.

Aceda a https://rss.example.com/api/ para executar automaticamente as verificações da configuração do servidor. Uma configuração funcional devolve PASS. Se a verificação falhar, confirme a definição AllowEncodedSlashes On do virtual host e o erro apresentado. Na aplicação, indique https://rss.example.com/api/greader.php como endereço do servidor, o seu utilizador do FreshRSS como nome de utilizador e a palavra-passe da API como palavra-passe.

A alternativa com Docker

Se preferir não manter o PHP e o Apache manualmente, o projeto disponibiliza uma imagem freshrss/freshrss oficial, e um ficheiro Compose fornece a aplicação e a respetiva base de dados em conjunto. A contrapartida é a habitual: menos componentes para gerir no host, mais uma camada para diagnosticar quando algo falha e, ainda assim, a necessidade de um reverse proxy para TLS (transport layer security). Se esta opção for mais adequada, os conceitos básicos do Docker Compose para um VPS explicam o formato do ficheiro, e a linha do cron passa a ser docker exec --user www-data freshrss php ./app/actualize_script.php.

Backups e atualizações

O seu estado depende de duas coisas: a base de dados e /srv/freshrss/data/. Exporte a primeira com sudo mysqldump freshrss > freshrss.sql, copie a segunda e mantenha ambas fora deste servidor. Também vale a pena exportar ocasionalmente a sua lista de subscrições em formato OPML, porque esse ficheiro transfere a lista de feeds para outros leitores compatíveis com OPML. O ficheiro não preserva definições específicas do FreshRSS, como a frequência de atualização, as credenciais, o user agent ou as regras de web scraping XPath; use uma exportação SQLite para preservar também essas definições.

A atualização consiste em extrair uma release mais recente sobre o mesmo diretório e executar novamente os comandos de propriedade. Siga o caminho de atualização versão a versão do projeto e verifique o FreshRSS após cada etapa. O FreshRSS aplica as suas próprias migrações da base de dados no carregamento da página seguinte. Faça primeiro um backup, porque uma migração falhada numa base de dados que não pode restaurar deixa o sistema num estado irrecuperável. Se instalou a partir de um tarball antigo, como 1.29.1, atualize para 1.30.4: as releases de segurança 1.30.x incluem rotação do ID de sessão quando há alterações de autenticação e limites para importações ZIP, enquanto a 1.30.4 também atualiza as imagens Docker Alpine alternativas para corrigir vulnerabilidades graves do PHP. Um leitor é um serviço de baixo risco para executar e um bom primeiro candidato se estiver a consultar uma lista do que vale a pena alojar por conta própria.

FAQ

Por que os meus feeds só são atualizados quando abro o FreshRSS?

Abrir a página não agenda a obtenção dos feeds. Sem um agendador, use o link de atualização para atualizar manualmente. Adicione a linha do cron que chama app/actualize_script.php como o utilizador www-data. Em seguida, execute o script manualmente uma vez e leia a saída. Se não produzir saída, verifique a saída de erros do PHP e os logs do FreshRSS. Depois, confirme que o utilizador do cron tem acesso de escrita a data/.

A minha aplicação móvel não consegue ligar-se, mas o site funciona. Porquê?

A Google Reader API coloca barras codificadas (%2F) nos caminhos dos pedidos, e o Apache rejeita-as por predefinição. Adicione AllowEncodedSlashes On dentro do virtual host e recarregue o Apache. Confirme a correção abrindo https://rss.example.com/api/. A verificação automática da configuração deve indicar PASS. Verifique também se a palavra-passe da API está definida no seu perfil, pois é diferente da palavra-passe de início de sessão.

Devo usar SQLite ou MariaDB?

O SQLite precisa da extensão php-sqlite3, mas não requer um servidor de bases de dados nem uma palavra-passe de base de dados para gerir. Cada utilizador recebe um ficheiro de base de dados SQLite separado. Assim, adicionar um segundo utilizador não cria contenção num único ficheiro partilhado nem exige MariaDB. Use MariaDB se quiser utilizar o servidor de bases de dados da sua stack LAMP. Mais tarde, é possível mudar entre os dois através dos comandos de exportação e importação. Portanto, esta não é uma decisão permanente.

O instalador falha ao escrever a configuração. Qual é o problema?

O PHP é executado como www-data no Apache, e esse utilizador não pode escrever num diretório pertencente a root. Execute novamente sudo chown -R www-data:www-data /srv/freshrss e sudo chmod -R g+w /srv/freshrss/data. Em seguida, inicie novamente o instalador. Se já tiver executado o instalador de linha de comandos como root, corrija a propriedade dos ficheiros que ele criou em data/ antes de tentar novamente.

De que recursos de servidor precisa um leitor RSS autoalojado?

Muito poucos. O FreshRSS foi concebido para funcionar em hardware modesto, mas o consumo de recursos depende dos seus feeds, do tamanho dos artigos e das definições de retenção. O espaço em disco aumenta com a retenção. Por isso, defina uma política de eliminação de artigos nas definições de arquivo em vez de manter tudo indefinidamente.