Alojar FreshRSS num VPS gerido: os seus feeds RSS no seu servidor

O que faz o FreshRSS

O FreshRSS é um agregador de feeds RSS autoalojado, escrito em PHP. O seu README descreve-o como leve, simples de utilizar, potente e personalizável, traduzido em mais de vinte línguas. É uma aplicação multiutilizador, com um modo de leitura anónima e etiquetas personalizadas.

• A leitura: as suas subscrições organizadas por categorias, etiquetas, favoritos e pesquisas guardadas.
• O WebSub: o FreshRSS recebe instantaneamente os novos artigos das fontes compatíveis, que os enviam em vez de esperarem pela atualização seguinte.
• A recolha de páginas: para um site sem feed RSS nem Atom, o FreshRSS lê ele próprio a página com regras XPath, e sabe também ler documentos JSON.
• A partilha: uma seleção de artigos pode ser republicada em HTML, RSS ou OPML.
• As aplicações: uma API para as aplicações móveis e de computador, uma interface de linha de comandos e extensões.

O FreshRSS é desenvolvido pela sua comunidade no GitHub, e o seu site oficial é editado pela comunidade FreshRSS. As extensões vivem num repositório separado, e a documentação dirige-se aos utilizadores, aos administradores e aos programadores.

O que permite a licença AGPL-3.0

O FreshRSS é publicado sob a GNU Affero General Public License, versão 3: o seu manifesto composer.json declara-a como AGPL-3.0, e o seu README remete para o texto da licença. Esse texto afirma uma permissão ilimitada de fazer correr o programa não modificado. Pode, portanto, utilizar a imagem publicada pelo projeto para a sua empresa e a sua equipa, sem licença para comprar.

O artigo 13 acrescenta uma condição própria da AGPL: se modificar o programa, a sua versão tem de oferecer a todos os que a utilizam à distância, pela rede, o meio de obter gratuitamente o seu código-fonte. Uma extensão de terceiros acrescentada ao volume extensions segue a sua própria licença.

A instalação com o Docker Compose

O projeto publica as suas imagens oficiais no Docker Hub, com o nome freshrss/freshrss, bem como um ficheiro Compose de exemplo. Num servidor com o Docker instalado, crie uma pasta freshrss e coloque nela este compose.yaml, tirado desse ficheiro e do README Docker:

volumes:
  data:
  extensions:

services:
  freshrss:
    image: freshrss/freshrss:latest
    container_name: freshrss
    hostname: freshrss
    restart: unless-stopped
    logging:
      options:
        max-size: 10m
    volumes:
      - data:/var/www/FreshRSS/data
      - extensions:/var/www/FreshRSS/extensions
    ports:
      - 127.0.0.1:8080:80
    environment:
      TZ: UTC
      CRON_MIN: '3,33'
      TRUSTED_PROXY: 172.16.0.1/12 192.168.0.1/16
    healthcheck:
      test: ["CMD", "cli/health.php"]
      timeout: 10s
      start_period: 60s
      start_interval: 11s
      interval: 75s
      retries: 3

docker compose up -d

• Uma porta publicada em 127.0.0.1: o FreshRSS só é acessível através do proxy inverso, instalado no mesmo servidor. O ficheiro de exemplo do projeto publica a porta 8080 para uma utilização local; aqui, o endereço 127.0.0.1 reserva-a ao proxy.
• O volume data guarda a configuração, as contas e, com o SQLite, a base de dados de cada utilizador. O README assinala que contém todos os dados pessoais. O Docker Compose dá-lhe o nome da pasta: freshrss_data.
• O volume extensions guarda as extensões de terceiros, se as acrescentar.
• TZ recebe o fuso horário do servidor, no formato PHP; por predefinição, UTC.
• TRUSTED_PROXY mantém o valor do ficheiro de exemplo: os intervalos privados de onde chegam os pedidos do proxy. Decide qual o endereço que entra nos registos, o do visitante ou o do proxy.
• A verificação de estado executa cli/health.php a intervalos regulares, para que o Docker saiba se a instância responde.

A etiqueta latest, a predefinida, acompanha a última versão numerada; edge acompanha a versão contínua; uma etiqueta como 1.30.4 fixa uma versão, e o sufixo -alpine dá o mesmo numa base Alpine em vez de Debian. A secção das atualizações volta a esta escolha.

Concluir a instalação

Com o proxy inverso instalado, abra o seu endereço HTTPS: o assistente de instalação pede a língua, verifica o servidor, propõe a escolha da base de dados e cria depois a conta de administrador, com a sua palavra-passe e o método de início de sessão. O SQLite funciona sem nada para preparar. A instalação faz-se também na linha de comandos, com cli/do-install.php e cli/create-user.php, executados através de docker exec --user www-data freshrss.

Quanto aos recursos, o README pede um servidor ligeiro, em Linux ou Windows, e assinala que o FreshRSS funciona até num Raspberry Pi 1, com tempos de resposta inferiores a um segundo, com 150 feeds e 22 000 artigos. O tamanho depende do número de utilizadores, de feeds e de artigos conservados. Num VPS gerido, descreva-nos a sua utilização e recomendamos-lhe o tamanho adequado.

HTTPS: o proxy inverso

Para a produção, o README Docker aconselha um proxy inverso no servidor anfitrião, que fornece o HTTPS. Escolha primeiro um nome de domínio ou um subdomínio, como rss.example.com, que aponte para o servidor com registos A e AAAA. O projeto recomenda o Traefik e publica para ele um ficheiro Compose completo, com os certificados Let's Encrypt e o redirecionamento de HTTP para HTTPS; dá também exemplos para o Apache, o Nginx e o Caddy.

Com o Caddy

O Caddy obtém o certificado e ativa o HTTPS por si próprio. Este bloco retoma o exemplo da documentação para um subdomínio, apontado aqui para a porta publicada em local:

rss.example.com {
  reverse_proxy 127.0.0.1:8080
}

Com o Nginx e o Certbot

Este bloco retoma o exemplo Nginx do README Docker para a raiz de um domínio, reduzido à porta 80 para deixar o Certbot instalar o HTTPS. As duas últimas linhas transmitem o cabeçalho Authorization, de que a API Google Reader precisa:

upstream freshrss {
  server 127.0.0.1:8080;
  keepalive 64;
}

server {
  listen 80;
  listen [::]:80;
  server_name rss.example.com;

  location / {
    proxy_pass http://freshrss/;
    proxy_redirect off;
    proxy_buffering off;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_read_timeout 90;

    proxy_set_header Authorization $http_authorization;
    proxy_pass_header Authorization;
  }
}

O Certbot instala depois o certificado e encarrega-se de o renovar:

sudo certbot --nginx

O endereço público: base_url

O FreshRSS guarda o seu endereço público em base_url, no ficheiro data/config.php. A API e o WebSub dependem dele: verifique que contém o seu endereço em https. O README Docker mostra onde encontrar este ficheiro no volume:

docker volume inspect freshrss_data
sudo nano /var/lib/docker/volumes/freshrss_data/_data/config.php
docker compose restart freshrss

'base_url' => 'https://rss.example.com/',

A atualização dos feeds: CRON_MIN

O FreshRSS vai buscar os novos artigos com o seu script app/actualize_script.php. A imagem Docker inclui uma tarefa agendada que o executa nos minutos indicados em CRON_MIN. Sem esta variável, ou com um valor vazio, a tarefa fica desativada e os feeds deixam de se atualizar sozinhos.

• O ritmo: o projeto recomenda cerca de duas execuções por hora, por exemplo 13,43; */20 também funciona.
• O limite: o script não atualiza o mesmo feed mais do que uma vez a cada vinte minutos, pelo que um calendário mais apertado não traz nada.
• O tempo real: o WebSub assume o papel para as fontes compatíveis. Precisa de um endereço público, lido em base_url, e o assistente de instalação ativa-o quando o servidor tem um.

Outro método documentado: uma tarefa agendada no servidor anfitrião, que chama o script dentro do contentor. Nesse caso, retire CRON_MIN do compose.yaml, para manter um único método:

7,37 * * * * root docker exec --user www-data freshrss php ./app/actualize_script.php > /tmp/FreshRSS.log 2>&1

Desde a versão 1.30.0, o FreshRSS recusa por predefinição os endereços da rede local, como 127.0.0.1, para se proteger da falsificação de pedidos do lado do servidor. Um serviço vizinho que produza feeds, como o RSS-Bridge, é autorizado através da variável INTERNAL_HOST_ALLOWLIST, na forma rss-bridge:80, ou na configuração do sistema. O valor * retira qualquer verificação, e a documentação considera-o inseguro.

As contas e o início de sessão

Na instalação, o FreshRSS propõe o início de sessão por formulário, que exige o JavaScript. É o método predefinido, e convém à maioria das instâncias. A documentação descreve outros:

A documentação avisa que o FreshRSS confia em qualquer endereço indicado em TRUSTED_PROXY: um proxy mal protegido permitiria a um atacante definir o cabeçalho e obter o acesso de administrador. Aqui, a porta só escuta em 127.0.0.1, o que a reserva ao proxy do próprio servidor. A documentação desaconselha também qualquer instância sem autenticação, logo que o servidor seja acessível a partir do exterior da sua rede.

As inscrições e os utilizadores

• Fechadas por predefinição: a configuração fixa o número de contas em 1, a do administrador. O formulário de inscrição só aparece se aumentar esse número, em Administração, Configuração do sistema; 0 retira qualquer limite.
• As contas criadas pelo administrador: Administração, Gestão dos utilizadores, com a língua, o nome de utilizador, a palavra-passe e o estatuto de administrador ou não.
• Uma nova autenticação é pedida antes das ações sensíveis, como promover um utilizador ou aplicar uma atualização, ao fim de 20 minutos por predefinição.
• A validação do endereço de e-mail é facultativa. Exige um servidor SMTP, definido com mailer e smtp no data/config.php: a documentação indica que o envio pela função mail do PHP ainda não é suportado nas imagens Docker oficiais.

Para uma instância partilhada por várias pessoas, a documentação aconselha a abrir as contas a pessoas de confiança e a manter a instância atrás de um proxy ou de uma firewall que bloqueie o acesso aos intervalos de endereços internos.

As aplicações móveis: as API Google Reader e Fever

O FreshRSS funciona no navegador, em ecrãs grandes e pequenos, e em aplicações para Android, iOS, Linux, Windows e macOS. Estas aplicações utilizam uma das suas duas API: a Google Reader, que o README considera a melhor, e a Fever, com funcionalidades mais limitadas, menos eficiente e menos segura.

1. Como administrador, na secção Autenticação, ative a opção que autoriza o acesso pela API.
2. Cada utilizador define uma palavra-passe de API no seu perfil. É distinta da palavra-passe principal, dá acesso a menos coisas e destina-se às situações menos seguras.
3. Na aplicação, introduza o endereço https://rss.example.com/api/greader.php, ou https://rss.example.com/api/fever.php para a Fever, com o nome de utilizador e essa palavra-passe de API.

Para verificar, a ligação apresentada ao lado da palavra-passe de API, no perfil, abre uma página de teste: PASS na verificação completa confirma que tudo funciona. A imagem Docker já configura o Apache para aceitar as barras codificadas, de que algumas aplicações precisam; com o Nginx à frente, mantenha a transmissão do cabeçalho Authorization.

O README mantém uma tabela das aplicações compatíveis, com a sua plataforma, a sua API e as suas funcionalidades: o Capy Reader e o Readrops no Android, o FeedFlow no telemóvel e no computador, o RSS Guard e o NewsFlash no computador, o ReadKit e o Reeder Classic no iOS e no macOS, entre outras.

SQLite, PostgreSQL, MySQL ou MariaDB

O FreshRSS integra o SQLite, que o README Docker descreve como a opção mais simples, com bom desempenho. A página dos requisitos recomenda o PostgreSQL 10 ou posterior, e aceita também o MariaDB 10.6 e o MySQL 8.0 ou posterior. A escolha faz-se no assistente de instalação.

Para o PostgreSQL, acrescente este serviço ao compose.yaml, tirado do ficheiro docker-compose-db.yml do projeto, e o volume db à lista dos volumes. A palavra-passe fica num ficheiro .env, ao lado do compose.yaml:

  freshrss-db:
    image: postgres:18
    container_name: freshrss-db
    hostname: freshrss-db
    restart: unless-stopped
    logging:
      options:
        max-size: 10m
    volumes:
      - db:/var/lib/postgresql
    environment:
      POSTGRES_DB: freshrss
      POSTGRES_USER: freshrss
      POSTGRES_PASSWORD: ${DB_PASSWORD}

DB_PASSWORD='a-long-unique-password'

No assistente, escolha o PostgreSQL e indique freshrss-db como anfitrião, com o utilizador, a palavra-passe e a base de dados freshrss.

Pode rever esta escolha mais tarde. A documentação descreve a passagem de uma base de dados para outra, do MySQL para o PostgreSQL, por exemplo, ou para uma versão principal mais recente do PostgreSQL: cli/db-backup.php copia a base de dados de cada utilizador para um ficheiro SQLite, e cli/db-restore.php carrega-a depois na nova base de dados.

As cópias de segurança

O README indica que o FreshRSS é fornecido sem qualquer garantia: são as suas cópias de segurança que guardam as suas subscrições, os seus artigos e as suas definições. Eis o que a documentação pede para copiar:

Os volumes, com o serviço parado

A documentação considera mais seguro parar o serviço durante as operações de manutenção. Os volumes Docker copiam-se com um contentor temporário, o método descrito na documentação do Docker:

docker compose stop freshrss
docker run --rm --volumes-from freshrss -v "$PWD":/backup ubuntu tar -czf /backup/freshrss-$(date +%F).tgz --exclude=data/cache -C /var/www/FreshRSS data extensions
docker compose start freshrss

As bases de dados, com o serviço a funcionar

Desde a versão 1.29.1, o FreshRSS sabe exportar ele próprio a base de dados de cada utilizador para um ficheiro SQLite, seja qual for a base de dados utilizada, e conservar apenas as mais recentes. Ative esta exportação no data/config.php:

'auto_sqlite_export' => [
    'enabled' => true,
    'retention' => 7,
],

Agende depois o comando no servidor, aqui todas as noites. Cada execução escreve data/users/<user>/sqlite-backups/<date>.sqlite e elimina os ficheiros para além dos sete últimos:

20 2 * * * root docker exec --user www-data freshrss cli/export-sqlite-auto.php --quiet

Com o PostgreSQL, acrescente uma exportação com a ferramenta da própria base de dados, como no README Docker. A opção -T retira o terminal, de que uma tarefa agendada não precisa:

docker compose exec -T freshrss-db pg_dump -U freshrss freshrss | gzip -9 > freshrss-postgres-$(date +%F).sql.gz

A exportação OPML, a partir da interface, guarda a sua lista de feeds, sem algumas definições próprias do FreshRSS, como os acessos ou as regras de recolha das páginas. Para uma cópia completa, guarde as exportações SQLite: colocadas no disco do servidor, entram também nas suas cópias de segurança noturnas.

Restaurar

1. Pare o FreshRSS com docker compose stop freshrss.
2. Volte a carregar o arquivo nos volumes: docker run --rm --volumes-from freshrss -v "$PWD":/backup ubuntu tar -xzf /backup/freshrss-YYYY-MM-DD.tgz -C /var/www/FreshRSS.
3. Com uma base de dados externa, restaure-a a partir da sua exportação, ou a partir dos ficheiros SQLite com cli/db-restore.php --delete-backup --force-overwrite.
4. Reinicie com docker compose start freshrss e verifique depois que os seus feeds e os seus artigos estão lá.

Repita este exercício de vez em quando, numa cópia: é assim que verifica que uma cópia de segurança funciona.

As atualizações

O README Docker dá dois comandos, a partir da pasta do compose.yaml. Os volumes mantêm-se no lugar:

docker compose pull
docker compose up -d

O FreshRSS publica em dois canais. As versões numeradas, etiqueta latest, saem algumas vezes por ano, sem calendário fixo, e as suas correções não são transpostas para as versões antigas. A versão contínua, etiqueta edge, recebe as novidades e as correções à medida que chegam: desde a versão 1.30.0, o projeto recomenda-a para obter mais depressa as correções de segurança.

• Uma cópia de segurança primeiro: a documentação pede uma cópia de data/, das extensões e da base de dados antes de cada atualização.
• Versão a versão: se estiver várias versões atrasado, passe por cada uma, por exemplo da 1.26.0 para a 1.27.1 antes da 1.28.1, verificando a cada etapa. Com o Docker, etiquetas como 1.29.1 tornam este percurso possível.
• As versões recentes: a 1.30.4, de 21 de outubro de 2026, é a quarta versão de segurança da série 1.30. Corrige vulnerabilidades do PHP nas imagens Alpine, depois da 1.30.3, que passou a imagem Debian predefinida para o Debian 13.

Para acompanhar as novas versões, o projeto publica um feed Atom das suas versões: subscreva-o na sua própria instância FreshRSS.

Quem faz o quê num VPS gerido

O autoalojamento exige cuidar do servidor para além da aplicação. Num VPS gerido, as nossas equipas assumem o servidor e acompanham a sua instância de forma proativa; o FreshRSS continua a ser o seu software, com as suas definições e os seus dados.

Se preferir que as nossas equipas intervenham na própria aplicação, este serviço é faturado à hora ou por pacote, com um orçamento comunicado antes da intervenção.