Winds 2.0 - A Beautiful Open Source RSS & Podcast App

What's new: In addition to the desktop apps there's now a web version of Winds available at https://winds.getstream.io/

Stream is sponsoring 1 person to work full time on this open source app: https://angel.co/stream/jobs/376455-senior-javascript-frontend-engineer

Winds is a beautiful open-source RSS and Podcast app created using React/Redux/Node. Use the free hosted version or run it on your own server and customize it as you see fit. Contributions are always appreciated. In fact we're planning a series of tutorials to help you get started. Activity Feeds & Discovery in Winds are powered by Stream, the app leverages Algolia for search, AWS for hosting, MongoDB Atlas for a hosted database (DBaaS), and SendGrid for email. All of these services have a free tier.

To get started with Winds 2.0, please visit https://getstream.io/winds/

TOCd

Roadmap
Powered By
- Stream
- Algolia
- MongoDB
- SendGrid
- AWS
Tutorials
Download
Contributing to Winds
Support
Maintenance & Contributions

Roadmap

Help us improve Winds and/or vote on the Roadmap for 2.1

Mark Read (partially implemented)
Playlist support (partially implemented)
Team support (share an activity feed with colleagues or friends to discover and collaborate)
Mobile application powered by React Native
SSO (Google & Twitter)
Folder Support
Listen to feed changes in realtime

Powered By

The full stack can be found on StackShare.io.

Stream

Stream is an API for building activity feeds. For Winds the follow suggestions and the list of articles from the feeds you follow is powered by Stream. Stream accounts are free for up to 3 million feed updates and handle personalization (machine learning) for up to 100 users.

Algolia

Algolia is used for lightning fast and relevant search. We use their JavaScript search client to easily setup the Winds search implementation. Algolia, accounts are free up to 10k records and 100k operations.

MongoDB

MongoDB Atlas provides a Database as a Service, and serves as the backend datastore for Winds.

Tutorials

The following tutorials will not only help you start contributing to Winds, but also provide inspiration for your next app.

Note: We're actively working on this portion of the README. To stay up to date with the latest information, please signup for the hosted version at https://getstream.io/winds.

Architecting a large React/Redux codebase
Building activity streams and newsfeeds on top of Stream
Implementing search with Algolia
Deploying to AWS ECS
MongoDB database schema design
Design thought process for Winds 2.0
PM2 in production environments
Creating a RESTful API design with Express.js
Preparing an Electron app for deployment to the macOS store
Deploying to the macOS store
Electron gotchas

Download

To download Winds 2.0, visit https://getstream.io/winds/.

Contributing to Winds

TL;DR

Commands:

brew install pkg-config cairo redis mongodb
brew services start mongodb
brew services start redis
cd winds/api
yarn
cd ../app
yarn

Sign up for both Stream and Algolia, and create the following .env file in the app directory, replacing the keys where indicated:

DATABASE_URI=mongodb://localhost/WINDS
CACHE_URI=redis://localhost:6379
JWT_SECRET=some-super-secret-arbitrary-jwt-string
API_PORT=8080
REACT_APP_API_ENDPOINT=http://localhost:8080
STREAM_API_BASE_URL=https://windspersonalization.getstream.io/personalization/v1.0

STREAM_APP_ID=YOUR_STREAM_APP_ID
STREAM_API_KEY=YOUR_STREAM_API_KEY
STREAM_API_SECRET=YOUR_STREAM_API_SECRET

REACT_APP_ALGOLIA_APP_ID=YOUR_ALGOLIA_APP_ID
REACT_APP_ALGOLIA_SEARCH_KEY=YOUR_ALGOLIA_SEARCH_ONLY_API_KEY
ALGOLIA_WRITE_KEY=YOUR_ALGOLIA_ADMIN_API_KEY

MERCURY_KEY=YOUR_KEY_HERE

Then run:

pm2 start process_dev.json
cd app && yarn start

Clone the Repo

git clone git@github.com:GetStream/winds.git

Install dependencies

The following instructions are geared towards Mac users who can use brew (Homebrew) to install most dependencies. Ubuntu users can use apt, and Windows users will have to install directly from the dependency's site. Non-debian-based Linux users will probably be able to figure it out on their own :)

cd Winds/app
yarn
cd ../api
yarn

Create a dotenv file

A .env file contains all configuration and connection strings for Winds.

Create a new file titled .env inside the app folder, and add the following:

DATABASE_URI=mongodb://localhost/WINDS
CACHE_URI=redis://localhost:6379
JWT_SECRET=some-super-secret-arbitrary-jwt-string
API_PORT=8080
REACT_APP_API_ENDPOINT=http://localhost:8080
STREAM_API_BASE_URL=https://windspersonalization.getstream.io/personalization/v1.0
MERCURY_KEY=YOUR_API_KEY_HERE

Start MongoDB Locally

Winds uses MongoDB as the main datastore - it contains all users, rss feeds, podcasts, episodes, articles, and shares.

If you're on a Mac, you can install MongoDB through Homebrew by running:

brew install mongodb

(You can also install MongoDB from the official MongoDB site.)

You can also run MongoDB in the background by running:

brew services start mongodb

Start Redis Locally

At Stream, we use Redis as an in-memory storage for the Winds podcast processing and RSS processing workers. It contains a list of podcasts and RSS feeds, which the workers pick up and process using the bull messaging system.

If you're on a Mac, you can install Redis through Homebrew by running:

brew install redis

(You can also install Redis from the official Redis site.)

Then, start Redis by running:

redis-server

...which creates (by default) a dump.rdb file in your current directory and stores a cached version of the database in that location.

You can also run Redis in the background by running:

brew services start redis

Stream

Sign up and Create a Stream App

To contribute to Winds, sign up for Stream to utilize the activity and timeline feeds.

(Reminder: Stream is free for applications with less than 3,000,000 updates per month.)

Sign up for Stream here
Create a new Stream app
Find the App ID, API Key, and API Secret for your new Stream app

Add your Stream App ID, API Key, and API Secret to your `.env`

Append the Stream App ID, API Key, and API secret to your .env file:

STREAM_APP_ID=YOUR_STREAM_APP_ID
STREAM_API_KEY=YOUR_STREAM_API_KEY
STREAM_API_SECRET=YOUR_STREAM_API_SECRET

Create Your Stream Feed Groups

Once you've signed in, create "feed groups" for your Stream app.

A "feed group" defines a certain type of feed within your application. Use the "Add Feed Group" button to create the following feeds:

feed group name	feed group type
`podcast`	flat
`rss`	flat
`user`	flat
`timeline`	flat
`user_episode`	flat
`user_article`	flat

It's fine to enable "Realtime Notifications" for each of these feed groups, though we won't be using those yet.

Algolia

Sign up for Algolia and Create an Algolia App and Index

In addition to Stream, you also need to sign up for Algolia, to contribute to Winds, for the search functionality.

(Algolia is free for applications with up to 10k records.)

Sign up for Algolia here
From the Applications page, click "New Application" and create a new Algolia application. (We recommend something similar to my-winds-app)
- (Select the datacenter that's closest to you.)
From the application page, select "Indices" and click "Add New Index". (We recommend something similar to winds-main-index)

Add Your Algolia Application Id, Search-Only Api Key and Admin Api Key to Your `.env` File

From your app, click the "API Keys" button on the left to find your app ID and API keys.

Append your Algolia application ID, search-only API Key and Admin API Key to your .env file to look like this:

REACT_APP_ALGOLIA_APP_ID=YOUR_ALGOLIA_APP_ID
REACT_APP_ALGOLIA_SEARCH_KEY=YOUR_ALGOLIA_SEARCH_ONLY_API_KEY
ALGOLIA_WRITE_KEY=YOUR_ALGOLIA_ADMIN_API_KEY

Start Backend Services

From the root directory, run:

pm2 start process_dev.json

To see logging information for all processes, run:

pm2 logs

Start Frontend Electron / Web App Server

cd app && yarn start

Running tests

Winds API server uses:

Mocha as testing framework
Chai as assertion library
Sinon as mocking library
nock as HTTP mocking library
mock-require as module mocking library

Tests are located in api/test folder.

File structure is intentionally mirroring files in api/src to simplify matching tests to tested code.

To run tests:

cd api && yarn run test

To run tests with extended stack traces (useful when debugging async issues):

cd api && yarn run test_deep

Adding new tests

Add your code to a file in api/test folder (preferably mirroring existing file from api/src folder).

Refer to Mocha documentation for examples of using BDD-like DSL for writing tests.

Modules are mocked in api/test-entry.js as mocks have to be installed before any modules are loaded.

Fixtures are loaded via loadFixture function from api/test/fixtures folder

Various utility functions are provided in api/test/util.js (See other tests for expamles of usage).

Building a Production Version

Build a production version of Winds by running:

./build.sh

This creates production-ready JS files in api/dist.

To run the production JS files:

pm2 start process_prod.json

Debugging RSS & Podcast Issues

Unfortunately there is no unified standard for RSS. Go to the api directory and run yarn link to make these commands available:

winds rss https://techcrunch.com/feed/

For podcasts:

winds podcast https://www.npr.org/rss/podcast.php\?id\=510289

For Open Graph scraping

winds og http://www.planetary.org/multimedia/planetary-radio/show/2018/0509-amy-mainzer-neowise.html

RSS Discovery

winds discover mashable.com

Article parsing (using mercury)

winds article https://alexiskold.net/2018/04/12/meet-12-startups-from-techstars-nyc-winter-2018-program/

Pull requests for improved RSS compatibility are much appreciated. Most of the parsing codebase is located in api/src/parsers/.

Support

All support is handled via GitHub Issues. If you're unfamiliar with creating an Issue on GitHub, please follow these instructions.

Maintenance and Contributions

Thank you to all of the maintainers and contributors who've helped Winds become what it is today and help it stay up and running every day. We couldn't do it without you!

Special Shoutouts To:

Primary Maintainers

Contributors

Revive RSS

RSS is an amazing open standard. It is probably the most pleasant way to stay up to date with the sites and podcasts you care about. Our reasons for contributing to Winds are explained in the blogpost Winds 2.0 It's time to Revive RSS. In this section we will list other open source and commercial projects that are having an impact on Reviving RSS:

License

ImgBotApp/Winds

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages