# 🐋 Awesome TTRSS

Docker Pulls Docker Stars Docker Automated build Docker Build Status FOSSA Status

# 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

(opens new window)

# 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 and password, please change them asap.
wangqiru/mercury-parser-api and wangqiru/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
SINGLE_USER_MODE: true will enable single user mode and disable user authentication, which means login will not be required. Please only enable this under a secure environment
DISABLE_USER_IN_DAYS: disable feed update for inactive users after X days without login, until the user performs a login
LOG_DESTINATION: error log destination to use, sql uses internal logging that can be read in Preferences -> System, syslog uses system log, blank value uses PHP logging. default to sql
FEED_LOG_QUIET: true will disable the printing of feed updating logs

# Configure HTTPS

TTRSS container itself doesn't handle HTTPS traffic. An example of configuring an Nginx reverse proxy with free SSL certificate from Let's Encrypt (opens new window) is shown below:

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;

    access_log /var/log/nginx/ttrssdev_access.log combined;
    error_log  /var/log/nginx/ttrssdev_error.log;

    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;
    }
}

If you want to place TTRSS under a subdirectory, such as https://mydomain.com/ttrss, please refer to the following：

    location /ttrss/ {
        rewrite /ttrss/(.*) /$1 break;
        proxy_redirect https://$http_host https://$http_host/ttrss;
        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 upgrades 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 12.x to 13.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) with database.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.

The legacy docker-compose file (supports Postgres 12) is archived as docker-compose.pg12.yml (opens new window), and will no longer be maintained.

# 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

# Fever API (opens new window)

Provide Fever API simulate.

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

This plugin cannot be enabled in conjunction with Fever API as global plugins, if you require both plugins:

In ENABLE_PLUGINS replace fever with remove_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)。