🐋 Awesome TTRSS​

About​

🐋 Awesome TTRSS aims to provide a powerfulDockerized all-in-one solution forTiny Tiny RSS, 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 atDigitalOcean.

Awesome TTRSS supports multiple architecturesx86 ✓arm32v7 ✓arm64v8 ✓, except the OpenCC API.

Deployment via Docker​

docker run -it --name ttrss --restart=always \-eSELF_URL_PATH=[ your public URL ]  \-eDB_HOST=[ your DB address ]  \-eDB_PORT=[ your DB port ]  \-eDB_NAME=[ your DB name ]  \-eDB_USER=[ your DB user ]  \-eDB_PASS=[ your DB password ]  \-p [public port ]:80  \-dwangqiru/ttrss

Deployment via Docker Compose​

docker-compose.yml include 4 docker images:

1. TTRSS
2. PostgreSQL
3. Mercury Parser API
4. OpenCC APIarm32v7 ✗arm64v8 ✗
5. RSSHub

Steps​

1. Downloaddocker-compose.yml to any directory.
2. Readdocker-compose.yml and change the settings (please ensure you have changed the password for postgres).
3. Rundocker compose up -d and wait for the deployment to finish.
4. Access ttrss via port 181, with default credentialsadmin andpassword, please change them asap.
5. 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 thatauth_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 to24 hours
• HTTP_PROXY: In format ofip:port, the global proxy for your TTRSS instance, to set proxy on a per feed basis, useOptions 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 theofficial tt-rss documentation.

Configure HTTPS​

TTRSS container itself doesn't handle HTTPS traffic. Examples of configuring a Caddy or an Nginx reverse proxy with free SSL certificate fromLet's Encrypt are shown below:

# Caddyfilettrssdev.henry.wang {    reverse_proxy 127.0.0.1:181    encode zstd gzip}

# nginx.confupstream 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 thatthe value in youSELF_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.

SinceTTRSS stopped releasing tags,wangqiru/ttrss:latest will sync withTTRSS' main branch 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:latestdocker compose up -d # If you didn't use docker compose, I'm sure you know what to do.

Auto Update​

The exampleDocker Compose includesWatchtower, 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​

This section demonstrates the steps to upgrade Postgres major version (from 15.x to 16.x) or migrate from other images to postgres:alpine.

1. Stop all the service containers:

   bash

   docker compose stop

2. 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.

3. Use the following command to dump all your data:

   bash

   docker exec postgres pg_dumpall -c -U YourUsername > export.sql

4. Delete the Postgres data volume~/postgres/data/.

5. Update your Docker Compose file (Note that theDB_NAME must not be changed) withdatabase.postgres section in the the latestdocker-compose.yml, and bring it up:

   bash

   docker compose up -d

6. Use the following command to restore all your data:

   bash

   cat export.sql | docker exec -i postgres psql -U YourUsername

7. Test if everything works fine, and now you may remove the backup in step 2.

Plugins​

Mercury Fulltext Extraction​

Fetch fulltext of articles via a self-hosted Mercury Parser API. A separate Mercury Parser API is required, the exampleDocker Compose has already includedsuch a server.

Steps​

1. Enablemercury-fulltext plugin in preference
2. Enter Mercury Parser API endpoint

Useservice.mercury:3000 for Mercury instance deployed via Awesome-TTRSS.

Extraction Button​

FreshRSS / Google Reader API​

A FreshRSS / Google Reader API Plugin for Tiny-Tiny RSS

Steps​

1. Navigate to the Preferences menu in Tiny Tiny RSS, and check the box under "General" titled "Enable API"
2. In Preferences, open the Plugin menu and enable "freshapi"
3. 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 usehttps://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.
4. 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​

Provide Fever API simulation.

Steps​

1. Enable API in preference
2. Enter a password for Fever in preference
3. In supported RSS readers, usehttps://[your url]/plugins/fever as the target server address, with your account and the password set in Step 2.
4. The plugin communicates with TTRSS using an unsalted MD5 hash,using HTTPS is strongly recommended.

OpenCC Simp-Trad Chinese Conversionarm32v7 ✗arm64v8 ✗​

Conversion between Traditional and Simplified Chinese viaOpenCC , a separateOpenCC API Server is required. The exampleDocker Compose has already includedsuch a server.

Steps​

1. Enableopencc plugin in preference
2. Enter OpenCC API endpoint
   

Useservice.opencc:3000 for OpenCC instance deployed via Awesome-TTRSS.

Conversion Button​

FeedReader API​

Provide FeedReader API support.

System plugin, enabled by addingapi_feedreader to the environment variableENABLE_PLUGINS.

Refer toFeedReader API for more details.

News+ API​

Provide a faster two-way synchronization for Android AppNews+ and iOS AppFiery Feeds with TTRSS.

System plugin, enabled by addingapi_newsplus to the environment variableENABLE_PLUGINS.

Refer toNews+ API for more details.

Feediron​

Provide the ability to manipulate article DOMs.

Refer toFeediron for more details.

Options per Feed​

Provide the ability to configure proxy, user-agent and SSL certificate verification on a per feed basis.

Refer toOptions per Feed for more details.

Remove iframe sandbox​

Remove the sandbox attribute on iframes, thus enabling playback of embedded video in feeds.

Refer toRemove iframe sandbox。

Wallabag v2​

Save articles to Wallabag.

Refer toWallabag v2。

Auth OIDC​

This is a system plugin, that allow users to connect through an OpenID Connect provider, like Keycloak, to TTRSS.

Enable it by addingauth_oidc to the environment variableENABLE_PLUGINS.

Then add the following environments variables with according values :

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 toAuth OIDC for more details.

RSSHub​

There is a minimal integration ofRSSHub in the exampleDocker Compose. Once enabled, you can add RSS feeds from RSSHub via internal URL (docker service discovery), for example:http://service.rsshub:3000/bbc.

For more information on configuring RSSHub, please refer toRSSHub Docs.

Themes​

Feedly​

RSSHub​

Recommendation​

• RSSHub is an interesting place for discovering RSS feeds.
• For iOS and macOS user, the integratedFever plugin suppliesReeder 5 backend support.
• For Android user, the integratedFever plugin suppliesNews+ backend support.
• For Linux user, the integratedFeedReader API suppliesFeedReader backend support.

Support and Help​

• Readthis guide might help.
• Open an issue viaGitHub issue.
• Direct donation to TTRSS.

Donation​

Please consider donations to supportTTRSS directly.

License​

MIT