# 🐋 Awesome TTRSS
# About
🐋 Awesome TTRSS aims to provide a powerful Dockerized all-in-one solution for Tiny Tiny RSS (opens new window), an open source RSS feed reader and aggregator written in PHP, with enhanced user experience via simplified deployment and a list of curated plugins.
# Special Thanks
# Deployment
A VPS is highly recommended to host your Awesome TTRSS instance, a VPS can be obtained from as little as $5/month at DigitalOcean (opens new window). Alternatively, you may request for personalized support, fully-managed service or fully-managed VPS via sponsoring Awesome TTRSS on its 💰OpenCollective page (opens new window).
Awesome TTRSS supports multiple architectures x86 ✓arm32v7 ✓arm64v8 ✓, except the OpenCC API.
# Deployment via docker
docker run -it --name ttrss --restart=always \
-e SELF_URL_PATH=[ your public URL ] \
-e DB_HOST=[ your DB address ] \
-e DB_PORT=[ your DB port ] \
-e DB_NAME=[ your DB name ] \
-e DB_USER=[ your DB user ] \
-e DB_PASS=[ your DB password ] \
-p [ public port ]:80 \
-d wangqiru/ttrss
# Deployment via Docker Compose
docker-compose.yml (opens new window) include 4 docker images:
- TTRSS (opens new window)
- PostgreSQL (opens new window)
- Mercury Parser API (opens new window)
- OpenCC API (opens new window) arm32v7 ✗arm64v8 ✗
# Steps
- Download docker-compose.yml (opens new window) to any directory.
- Read
docker-compose.yml
and change the settings (please ensure you have changed the password for postgres). - Run
docker compose up -d
and wait for the deployment to finish. - Access ttrss via port 181, with default credentials
admin
andpassword
, please change them asap. wangqiru/mercury-parser-api
andwangqiru/opencc-api-server
are optional service containers to support additional features, removing them will not affect TTRSS's basic functionalities.
# Supported Environment Variables
- SELF_URL_PATH: the url to your TTRSS instance. 🔴 Please note that this value should be consistent with the URL you see in your browser address bar, otherwise TTRSS will not start.
- DB_HOST: the address of your database
- DB_PORT: the port of your database
- DB_NAME: the name of your database
- DB_USER: the user of your Database
- DB_PASS: the password of your database
- DB_USER_FILE: Docker Secrets support(alternative to DB_USER), the file containing the user of your database
- DB_PASS_FILE: Docker Secrets support(alternative to DB_PASS), the file containing the password of your database
- ENABLE_PLUGINS: the plugins you'd like to enable as global plugins, note that
auth_internal
is required - ALLOW_PORTS: comma-separated port numbers, eg:
1200,3000
. Allow subscription of non-'80,443' port feed. 🔴 Use with caution. - SESSION_COOKIE_LIFETIME: the expiry time in hours for your login session cookie in hours, default to
24
hours - HTTP_PROXY:
ip:port
, the global proxy for your TTRSS instance, to set proxy on a per feed basis, use Options per Feed - DISABLE_USER_IN_DAYS: disable feed update for inactive users after X days without login, until the user performs a login
- FEED_LOG_QUIET:
true
will disable the printing of feed updating logs
For more environment variables, please refer to the official tt-rss repo (opens new window).
# Configure HTTPS
TTRSS container itself doesn't handle HTTPS traffic. Examples of configuring a Caddy or an Nginx reverse proxy with free SSL certificate from Let's Encrypt (opens new window) are shown below:
# Caddyfile
ttrssdev.henry.wang {
reverse_proxy 127.0.0.1:181
encode zstd gzip
}
# nginx.conf
upstream ttrssdev {
server 127.0.0.1:181;
}
server {
listen 80;
server_name ttrssdev.henry.wang;
return 301 https://ttrssdev.henry.wang$request_uri;
}
server {
listen 443 ssl;
gzip on;
server_name ttrssdev.henry.wang;
ssl_certificate /etc/letsencrypt/live/ttrssdev.henry.wang/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/ttrssdev.henry.wang/privkey.pem;
location / {
proxy_redirect off;
proxy_pass http://ttrssdev;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Ssl on;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Frame-Options SAMEORIGIN;
client_max_body_size 100m;
client_body_buffer_size 128k;
proxy_buffer_size 4k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;
proxy_temp_file_write_size 64k;
}
}
🔴 Please note that the value in you SELF_URL_PATH
should be changed as well.
# Update
Awesome TTRSS automatically keeps up with TTRSS by mirroring the official releases, this means update can be issued frequently.
TTRSS stopped releasing tags (opens new window). wangqiru/ttrss:latest
will sync with TTRSS' main branch (opens new window) periodically.
# Manual Update
You can fetch the latest image manually:
docker pull wangqiru/ttrss:latest
# docker pull wangqiru/mercury-parser-api:latest
# docker pull wangqiru/opencc-api-server:latest
docker compose up -d # If you didn't use docker compose, I'm sure you know what to do.
# Auto Update
The example Docker Compose includes Watchtower (opens new window), which automatically pulls all containers included in Awesome TTRSS (and other containers running on your system) and refreshes your running services. By default, it's disabled, make sure it will not affect your other service containers before enabling this.
To exclude images, check the following for disabling auto update for containers:
service.mercury:
image: wangqiru/mercury-parser-api:latest
container_name: mercury
expose:
- 3000
restart: always
# ⬇️ this prevents Watchtower from auto updating mercury-parser-api
labels:
- com.centurylinklabs.watchtower.enable=false
# Database Upgrade or Migration
Postgres major version upgrades (15->16) will require some manual operations. Sometimes breaking changes will be introduced to further optimize Awesome TTRSS.
# Steps
WARNING
Do not skip multiple major versions when upgrading Postgres, for example, upgrading from 13.x to 16.x directly is not supported and may cause data loss.
This section demonstrates the steps to upgrade Postgres major version (from 15.x to 16.x) or migrate from other images to postgres:alpine.
Stop all the service containers:
docker compose stop
Copy the Postgres data volume
~/postgres/data/
(or the location specified in your Docker Compose file) to somewhere else as a backup, THIS IS IMPORTANT.Use the following command to dump all your data:
docker exec postgres pg_dumpall -c -U YourUsername > export.sql
Delete the Postgres data volume
~/postgres/data/
.Update your Docker Compose file (Note that the
DB_NAME
must not be changed) withdatabase.postgres
section in the the latest docker-compose.yml (opens new window), and bring it up:docker compose up -d
Use the following command to restore all your data:
cat export.sql | docker exec -i postgres psql -U YourUsername
Test if everything works fine, and now you may remove the backup in step 2.
# Plugins
# Mercury Fulltext Extraction (opens new window)
Fetch fulltext of articles via a self-hosted Mercury Parser API. A separate Mercury Parser API is required, the example Docker Compose has already included such a server (opens new window).
# Steps
- Enable
mercury-fulltext
plugin in preference - Enter Mercury Parser API endpoint
Use service.mercury:3000
for Mercury instance deployed via Awesome-TTRSS.
# Extraction Button
# FreshRSS / Google Reader API (opens new window)
A FreshRSS / Google Reader API Plugin for Tiny-Tiny RSS
# Steps
- Navigate to the Preferences menu in Tiny Tiny RSS, and check the box under "General" titled "Enable API"
- In Preferences, open the Plugin menu and enable "freshapi"
- When configuring your mobile app, select either "FreshRSS" or "Google Reader API". You'll need to point your client to your TT-RSS installation, depending on your setup. If you're using a subdomain to host TT-RSS then use
https://yoursubdomain.yourdomain.com/plugins.local/freshapi/api/greader.php
. If you're running on the root domain, usehttps://yourdomain.com/plugins.local/freshapi/api/greader.php
as the server URL. - Use your standard TT-RSS username and password. If you've enabled 2 Factor Authentication (2FA) generate and use an App Password. As with all plugins which handle authentication, using HTTPS is strongly recommended.
# Fever API (opens new window)
Provide Fever API simulation.
# Steps
- Enable API in preference
- Enter a password for Fever in preference
- In supported RSS readers, use
https://[your url]/plugins/fever
as the target server address, with your account and the password set in Step 2. - The plugin communicates with TTRSS using an unsalted MD5 hash, using HTTPS is strongly recommended.
# OpenCC Simp-Trad Chinese Conversion (opens new window) arm32v7 ✗arm64v8 ✗
Conversion between Traditional and Simplified Chinese via OpenCC (opens new window) , a separate OpenCC API Server (opens new window) is required. the example Docker Compose has already included such a server (opens new window).
# Steps
- Enable
opencc
plugin in preference - Enter OpenCC API endpoint
Use service.opencc:3000
for OpenCC instance deployed via Awesome-TTRSS.
# Conversion Button
# FeedReader API (opens new window)
Provide FeedReader API support.
System plugin, enabled by adding api_feedreader
to the environment variable ENABLE_PLUGINS.
Refer to FeedReader API (opens new window) for more details.
# News+ API (opens new window)
Provide a faster two-way synchronization for Android App News+ (opens new window) and iOS App Fiery Feeds (opens new window) with TTRSS.
System plugin, enabled by adding api_newsplus
to the environment variable ENABLE_PLUGINS.
Refer to News+ API (opens new window) for more details.
# Feediron (opens new window)
Provide the ability to manipulate article DOMs.
Refer to Feediron (opens new window) for more details.
# Options per Feed (opens new window)
Provide the ability to configure proxy, user-agent and SSL certificate verification on a per feed basis.
Refer to Options per Feed (opens new window) for more details.
# Remove iframe sandbox (opens new window)
WARNING
If you are getting data via fever api, enable it by adding remove_iframe_sandbox
to the environment variable ENABLE_PLUGINS.
This plugin cannot be enabled in conjunction with Fever API
as global plugins, if you require both plugins:
- In
ENABLE_PLUGINS
replacefever
withremove_iframe_sandbox
to enable this as a global plugin. - Enable
Fever API
in the TTRSS preferences panel after login, as a local plugin.
Remove the sandbox attribute on iframes, thus enabling playback of embedded video in feeds.
Refer to Remove iframe sandbox (opens new window)。
# Wallabag v2 (opens new window)
Save articles to Wallabag.
Refer to Wallabag v2 (opens new window)。
# Auth OIDC (opens new window)
This is a system plugin, that allow users to connect through an oidc provider, like Keycloak, to TTRSS.
System plugin, enabled by adding auth_oidc
to the environment variable ENABLE_PLUGINS.
Then add the following environments variables with according values :
```yaml
AUTH_OIDC_NAME: 'IDP provider name displayed'
AUTH_OIDC_URL: 'https://oidc.hostname.com'
AUTH_OIDC_CLIENT_ID: 'test-rss'
AUTH_OIDC_CLIENT_SECRET: 'your-secret-token'
```
Refer to Auth OIDC (opens new window) for more details.
# Themes
# Feedly (opens new window)
# RSSHub (opens new window)
# Recommendation
- RSSHub (opens new window) is an interesting place for discovering RSS feeds.
- For iOS and macOS user, the integrated Fever plugin (opens new window) supplies Reeder 5 (opens new window) backend support.
- For Android user, the integrated Fever plugin (opens new window) supplies News+ (opens new window) backend support.
- For Linux user, the integrated FeedReader API (opens new window) supplies FeedReader (opens new window) backend support.
# Support and Help
- You may request for personalized support via sponsoring Awesome TTRSS on its 💰OpenCollective page (opens new window).
- Read this guide (opens new window) might help.
- Open an issue via GitHub issue (opens new window).
- Direct donation to TTRSS (opens new window).
# Donation
PayPal | WeChat Pay | OpenCollective |
---|---|---|
(opens new window) | 💰OpenCollective page (opens new window) |
# License
MIT