Hospedar FreshRSS em um VPS gerenciado: seus feeds RSS em seu servidor

O que o FreshRSS faz

O FreshRSS é um agregador de feeds RSS auto-hospedado, escrito em PHP. O README dele o descreve como leve, fácil de usar, poderoso e personalizável, traduzido em mais de vinte idiomas. É uma aplicação multiusuário, com um modo de leitura anônima e tags personalizadas.

• A leitura: suas assinaturas organizadas em categorias, tags, favoritos e buscas salvas.
• O WebSub: o FreshRSS recebe na hora os novos artigos das fontes compatíveis, que os enviam em vez de esperar a próxima atualização.
• A raspagem de páginas: para um site sem feed RSS nem Atom, o FreshRSS lê a própria página com regras XPath, e também sabe ler documentos JSON.
• O compartilhamento: uma seleção de artigos pode ser republicada em HTML, RSS ou OPML.
• Os aplicativos: uma API para os aplicativos de celular e de desktop, uma interface de linha de comando e extensões.

O FreshRSS é desenvolvido pela comunidade dele no GitHub, e o site oficial é publicado pela comunidade FreshRSS. As extensões ficam em um repositório à parte, e a documentação atende usuários, administradores e desenvolvedores.

O que a licença AGPL-3.0 permite

O FreshRSS é publicado sob a GNU Affero General Public License, versão 3: o manifesto composer.json dele a declara como AGPL-3.0, e o README remete ao texto da licença. Esse texto afirma uma permissão irrestrita de rodar o programa não modificado. Você pode, portanto, usar a imagem publicada pelo projeto para sua empresa e sua equipe, sem licença a comprar.

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

A instalação com Docker Compose

O projeto publica as imagens oficiais no Docker Hub, com o nome freshrss/freshrss, junto com um arquivo Compose de exemplo. Em um servidor com o Docker instalado, crie uma pasta chamada freshrss e coloque nela este compose.yaml, extraído desse arquivo 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ó é acessado pelo proxy reverso, instalado no mesmo servidor. O arquivo de exemplo do projeto publica a porta 8080 para um uso local; o endereço 127.0.0.1 a reserva aqui ao proxy.
• O volume data guarda a configuração, as contas e, com o SQLite, o banco de cada usuário. O README lembra que ele contém todos os dados pessoais. O Docker Compose o nomeia a partir da pasta: freshrss_data.
• O volume extensions guarda as extensões de terceiros, se você acrescentar alguma.
• TZ recebe o fuso horário do servidor, no formato do PHP; o padrão é UTC.
• TRUSTED_PROXY mantém o valor do arquivo de exemplo: as faixas privadas de onde vêm as requisições do proxy. Ele decide qual endereço vai para os logs, o do visitante ou o do proxy.
• A verificação de saúde executa cli/health.php em intervalos regulares, para que o Docker saiba se a instância responde.

A tag latest, a padrão, acompanha a última versão numerada; edge acompanha a versão contínua; uma tag como 1.30.4 fixa uma versão, e o sufixo -alpine dá o mesmo em uma base Alpine em vez de Debian. A seção sobre as atualizações volta a essa escolha.

Concluir a instalação

Com o proxy reverso no lugar, abra seu endereço HTTPS: o assistente de instalação pede o idioma, verifica o servidor, propõe a escolha do banco e cria a conta de administrador, com a senha e o método de login. O SQLite funciona sem nada a preparar. A instalação também é feita pela linha de comando, com cli/do-install.php e cli/create-user.php, executados por docker exec --user www-data freshrss.

Quanto aos recursos, o README pede um servidor leve, com Linux ou Windows, e observa que o FreshRSS roda até em um Raspberry Pi 1, com tempos de resposta abaixo de um segundo, com 150 feeds e 22.000 artigos. O tamanho depende do número de usuários, de feeds e de artigos guardados. Em um VPS gerenciado, descreva-nos o uso e recomendamos o tamanho adequado.

HTTPS: o proxy reverso

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

Com o Caddy

O Caddy obtém o certificado e ativa o HTTPS sozinho. Este bloco retoma o exemplo da documentação para um subdomínio, apontado aqui para a porta publicada localmente:

rss.example.com {
  reverse_proxy 127.0.0.1:8080
}

Com o Nginx e o Certbot

Este bloco retoma o exemplo de 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 repassam 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;
  }
}

Em seguida, o Certbot instala o certificado e cuida de renová-lo:

sudo certbot --nginx

O endereço público: base_url

O FreshRSS guarda o endereço público dele em base_url, no arquivo data/config.php. A API e o WebSub dependem dele: verifique se ele traz seu endereço em https. O README Docker mostra onde encontrar esse arquivo 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 busca os novos artigos com o script app/actualize_script.php. A imagem Docker traz uma tarefa agendada que o executa nos minutos indicados em CRON_MIN. Sem essa 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 de uma vez a cada vinte minutos, então um agendamento mais apertado não traz nada.
• O tempo real: o WebSub assume para as fontes compatíveis. Ele precisa de um endereço público, lido em base_url, e o assistente de instalação o ativa quando o servidor tem um.

Outro método documentado: uma tarefa agendada no servidor hospedeiro, que chama o script dentro do contêiner. 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 padrão os endereços da rede local, como 127.0.0.1, para se proteger da falsificação de requisições do lado do servidor. Um serviço vizinho que produz feeds, como o RSS-Bridge, é autorizado pela variável INTERNAL_HOST_ALLOWLIST, na forma rss-bridge:80, ou na configuração do sistema. O valor * retira toda verificação, e a documentação o considera inseguro.

As contas e o login

Na instalação, o FreshRSS propõe o login por formulário, que exige JavaScript. É o método padrão, e ele convém à maioria das instâncias. A documentação descreve outros:

A documentação avisa que o FreshRSS confia em qualquer endereço listado em TRUSTED_PROXY: um proxy mal protegido permitiria que um invasor definisse o cabeçalho e obtivesse o acesso de administrador. Aqui, a porta escuta apenas em 127.0.0.1, o que a reserva ao proxy do próprio servidor. A documentação também desaconselha qualquer instância sem autenticação a partir do momento em que o servidor é acessível de fora de sua rede.

Os cadastros e os usuários

• Fechados por padrão: a configuração fixa o número de contas em 1, a do administrador. O formulário de cadastro só aparece se você aumentar esse número, em Administração, Configuração do sistema; 0 retira todo limite.
• As contas criadas pelo administrador: Administração, Gerenciar usuários, com o idioma, o nome de usuário, a senha e a indicação de que a conta é de administrador ou não.
• Uma nova autenticação é exigida antes das ações sensíveis, como promover um usuário ou aplicar uma atualização, após 20 minutos por padrão.
• A validação do endereço de e-mail é opcional. Ela exige um servidor SMTP, configurado com mailer e smtp em 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 compartilhada por várias pessoas, a documentação aconselha abrir as contas a pessoas de confiança e manter a instância atrás de um proxy ou de um firewall que bloqueie o acesso às faixas de endereços internos.

Os aplicativos de celular: as APIs Google Reader e Fever

O FreshRSS funciona no navegador, em telas grandes e pequenas, e em aplicativos para Android, iOS, Linux, Windows e macOS. Esses aplicativos usam uma de suas duas APIs: Google Reader, que o README considera a melhor, e Fever, com recursos mais limitados, menos eficiente e menos segura.

1. Como administrador, na seção Autenticação, ative a opção que autoriza o acesso pela API.
2. Cada usuário define uma senha de API em seu perfil. Ela é distinta da senha principal, dá acesso a menos coisas e é prevista para situações menos seguras.
3. No aplicativo, informe o endereço https://rss.example.com/api/greader.php, ou https://rss.example.com/api/fever.php para o Fever, com o nome de usuário e essa senha de API.

Para verificar, o link exibido ao lado da senha 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 alguns aplicativos precisam; com o Nginx na frente, mantenha o repasse do cabeçalho Authorization.

O README mantém uma tabela dos aplicativos compatíveis, com a plataforma, a API e os recursos de cada um: Capy Reader e Readrops no Android, FeedFlow no celular e no desktop, RSS Guard e NewsFlash no desktop, ReadKit e Reeder Classic no iOS e no macOS, entre outros.

SQLite, PostgreSQL, MySQL ou MariaDB

O FreshRSS traz o SQLite integrado, que o README Docker descreve como a opção mais simples, com bom desempenho. A página de requisitos recomenda o PostgreSQL 10 ou mais recente e também aceita o MariaDB 10.6 e o MySQL 8.0 ou mais recentes. A escolha é feita no assistente de instalação.

Para o PostgreSQL, acrescente este serviço ao compose.yaml, extraído do arquivo docker-compose-db.yml do projeto, e o volume db à lista dos volumes. A senha vai em um arquivo .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 PostgreSQL e informe freshrss-db como host, com o usuário, a senha e o banco freshrss.

Você pode rever essa escolha mais tarde. A documentação descreve a passagem de um banco a outro, do MySQL para o PostgreSQL, por exemplo, ou para uma versão principal mais recente do PostgreSQL: cli/db-backup.php copia o banco de cada usuário em um arquivo SQLite, e depois cli/db-restore.php o carrega no novo banco.

Os backups

O README afirma que o FreshRSS é fornecido sem nenhuma garantia: seus backups guardam suas assinaturas, seus artigos e suas configurações. Veja o que a documentação pede para salvar:

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 são copiados com um contêiner 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

Os bancos, com o serviço em funcionamento

Desde a versão 1.29.1, o FreshRSS sabe exportar sozinho o banco de cada usuário para um arquivo SQLite, seja qual for o banco usado, e manter apenas os mais recentes. Ative essa exportação em data/config.php:

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

Agende então o comando no servidor, aqui toda noite. Cada execução grava data/users/<user>/sqlite-backups/<date>.sqlite e exclui os arquivos 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 do próprio banco, como no README Docker. A opção -T dispensa o terminal, que uma tarefa agendada não usa:

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

A exportação OPML, pela interface, salva sua lista de feeds, sem algumas configurações próprias do FreshRSS, como as credenciais ou as regras de raspagem de páginas. Para uma cópia completa, guarde as exportações SQLite: colocadas no disco do servidor, elas também entram nos backups noturnos dele.

Restaurar

1. Pare o FreshRSS com docker compose stop freshrss.
2. Recarregue 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 um banco externo, restaure-o a partir da exportação dele, ou a partir dos arquivos SQLite com cli/db-restore.php --delete-backup --force-overwrite.
4. Reinicie com docker compose start freshrss e verifique se seus feeds e seus artigos estão lá.

Repita esse exercício de tempos em tempos, em uma cópia: é assim que você verifica se um backup funciona.

As atualizações

O README Docker dá dois comandos, a partir da pasta do compose.yaml. Os volumes continuam no lugar:

docker compose pull
docker compose up -d

O FreshRSS publica em dois canais. As versões numeradas, tag latest, saem algumas vezes por ano, sem calendário fixo, e as correções delas não são levadas às versões anteriores. A versão contínua, tag edge, recebe os novos recursos e as correções à medida que chegam: desde a versão 1.30.0, o projeto a recomenda para receber mais rápido as correções de segurança.

• O backup primeiro: a documentação pede um backup de data/, das extensões e do banco antes de cada atualização.
• Versão por versão: se você estiver várias versões atrasado, passe por cada uma, por exemplo da 1.26.0 à 1.27.1 antes da 1.28.1, verificando a cada etapa. Com o Docker, tags como 1.29.1 tornam esse caminho 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. Ela corrige vulnerabilidades do PHP nas imagens Alpine, depois da 1.30.3, que passou a imagem Debian padrão para o Debian 13.

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

Quem faz o quê em um VPS gerenciado

A auto-hospedagem exige cuidar do servidor além da aplicação. Em um VPS gerenciado, nossas equipes assumem o servidor e acompanham sua instância de forma proativa; o FreshRSS continua sendo seu software, com as configurações e os dados dele.

Se você preferir que nossas equipes intervenham na própria aplicação, esse serviço é cobrado por hora ou por valor fechado, com o orçamento informado antes da intervenção.