RSS
A simple, opinionated, RSS feed aggregator.
Features
The following features are built into the application:
- Supports RSS and ATOM formats.
- Regular auto-fetching of RSS feeds.
- Every hour by default, configurable down to 5 mins.
- Custom feed names and colors.
- Feed-based tags for categorization.
- 3 different post layout modes (card, list, compact).
- Fetching of page open-graph images.
- Feeds managed via a single plaintext file.
- System-based dark/light theme.
- Post title/description search.
- Ready-to-use docker image.
- Mobile screen compatible.
Limitations
The below possibly expected features are missing from this application. This is not a list of planned features. Please see the Low Maintenance Project section below for more info.
- No import of full post/article content.
- No feed management via the UI.
- No user system or user management system.
- No authentication or authorization built-in.
- No customization, extension or plugin system.
- No organisation upon simple feed-level tagging.
- Error handling is limited and will likely not alert clearly upon issue.
Upon the above, it's quite likely you'll come across issues. This project was created to meet a personal need while learning some new technologies. Much of the logic is custom written instead of using battle-tested libraries.
Docker Usage
A pre-built docker image is available to run the application. Storage data is confined to a single
/app/storage directory for easy volume mounting. Port 80 is exposed by default for application access. This application does not support HTTPS, for that you should instead use a proxy layer such as nginx.Docker Run Command Example
In the below command, the application will be accessible at http://localhost:8080 on the host and the files would be stored in a
/home/barry/rss directory. In this example, feeds would be configured in a /home/barry/rss/feeds.txt file.docker run -d \ --restart unless-stopped \ -p 8080:80 \ -v /home/barry/rss:/app/storage \ ghcr.io/ssddanbrown/rss:latest
Docker Compose Example
In the below docker-compose.yml example, the application will be accessible at http://localhost:8080 on the host and the files would be stored in a
./rss-files directory relative to the docker-compose.yml file. In this example, feeds would be configured in a ./rss-files/feeds.txt file.--- version: "2" services: rss: image: ghcr.io/ssddanbrown/rss:latest container_name: rss environment: - APP_NAME=RSS volumes: - ./rss-files:/app/storage ports: - "8080:80" restart: unless-stopped
Feed Configuration
Feed configuration is handled by a plaintext file on the host system. By default, using our docker image, this configuration would be located in a feeds.txt file within the path you mounted to
/app/storage.The format of this file can be seen below:
https://feed.url.com/feed.xml feed-name #tag-a #tag-b https://example.com/feed.xml Example #updates #news # Lines starting with a hash are considered comments. # Empty lines are fine and will be ignored. # Underscores in names will be converted to spaces. https://example.com/feed-b.xml News_Site #news # Feed color can be set using square brackets after the name. # The color must be a CSS-compatible color value. https://example.com/feed-c.xml Blue_News[#0078b9] #news #blue
App Configuration
The application allows some configuration through variables. These can be set via the
.env file or, when using docker, via environment variables.# The name of the application. # Only really shown in the title/browser-tab. APP_NAME=RSS # The path to the config file. # Defaults to `storage/feeds.txt` within the application folder. APP_CONFIG_FILE=/app/storage/feeds.txt # Enable or disable the loading of post thumbnails. # Does not control them within the UI, but controls the fetching # when posts are fetched. # Defaults to true. APP_LOAD_POST_THUMBNAILS=true # The number of minutes before a feed is considered outdated and # therefore should be updated upon request. # This effectively has a minimum of 5 minutes in the docker setup. APP_FEED_UPDATE_FREQUENCY=60
Usage Behind a Reverse Proxy
When using behind a reverse proxy, ensure common forwarding headers are set so that the application can properly detect the right host and path to use. The below shows a sub-path proxy config location block for nginx. Note the
X-Forwarded-Prefix header to make the application aware of sub-path usage.location /rss/ { proxy_pass http://container-ip:80/; 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-Host $host; proxy_set_header X-Forwarded-Port $server_port; proxy_set_header X-Forwarded-Prefix "/rss/"; proxy_redirect off; }
Manual Install
Manually installing the application is not recommended unless you are performing development work on the project. Instead, use of the docker image is advised.
This project is based upon Laravel so the requirements and install process are much the same. You will need git, PHP, composer and NodeJS installed. Installation would generally be as follows:
# Clone down and enter the project git clone https://github.com/ssddanbrown/rss.git cd rss # Install PHP dependencies via composer # This will check you meet the minimum PHP version and extensions required. composer install # Create database file touch storage/database/database.sqlite # Copy config, generate app key, migrate database & link storage cp .env.example .env php artisan key:generate php artisan migrate php artisan storage:link # Install JS dependencies & build CSS/JS npm install npm run build
For a production server you'd really want to have a webserver active to server the
public directory and handle PHP. You'd also need a process to run the laravel queue system in addition to a cron job to run the schedule.On a development system, These can be done like so:
# Serve the app php artisan serve # Watch the queue php artisan queue:listen # Work the schedule php artisan schedule:work
Low Maintenance Project
This is a low maintenance project. The scope of features and support are purposefully kept narrow for my purposes to ensure longer term maintenance is viable. I'm not looking to grow this into a bigger project at all.
Issues and PRs raised for bugs are perfectly fine assuming they don't significantly increase the scope of the project. Please don't open PRs for new features that expand the scope.
Development
This project uses PHPUnit for testing. Tests will use their own in-memory SQLite instance. Tests can be ran like so:
./vendor/bin/phpunit
PHP CS Fixer is used for formatting. This can be ran like so:
./vendor/bin/php-cs-fixer fix
