River2 Blog

News and updates about the River2 aggregator.

Category Archives: Features

Storing your rivers in Amazon S3

The reason to store your rivers in Amazon S3 is that you get the infinite scaling of S3, compared to the very finite scaling of EC2 (esp if you’re using a micro-instance).

1. If you haven’t already done so, configure the OPML Editor for S3.

2. Using the AWS dashboard, create a new S3 bucket. You can name it whatever you like, but it must be unique across all of S3. If your initials are BM, something like bmRiverBucket probably will be unique. Remember what you named the bucket.

3. Using your remote desktop app, access your server. On the server machine, bring the OPML app to the front.

4. Bring config.root to the front.

5. Navigate to config.river2.prefs.static.

6. In s3Path, enter a forward-slash (/) followed by the name of your bucket followed by a forward-slash. Something like /bmRiverBucket/.

7. Set flSynchToS3 to true.

8. You can leave s3Url empty, River2 will fill it in for you.

After your next scan, look in the bucket. If it worked, you should see your static files, a full set for each user, and one for your main river.

How to make your static river “beautiful”

I’ve been working with the people on the River Of News mail list to make wikiriver.org nicer-to-look-at. Of course it’s just a river maintained by the River2 tool. So once we had it so that one river could look nicer, we can make them all nicer.

Here’s how to do it…

1. Bring config.root to the front and navigate to config.river2.users.

2. Open the user whose river you want to beautify.

3. Open prefs then beautifulRiver and look for a boolean value named flBeautifulIsIndex.

4. Click in the Value field and select false, type true in its place and press Return.

That’s it. The next time your river scans this one will get a new look.

If you want to beautify your main river, navigate to config.river2.prefs.beautifulRIver and change its flBeautifulIsIndex value to true.

How to map a domain to your river

On the ec2-for-poets list, Donovan Watts asks how to access his river through a simple domain name.

Doing so involves editing the object database, which is straightforward, but should be done with care.

To prepare, make a note of the IP address of the server. Using the web interface of your domain registrar, map the name you want to use to the IP address of the server. Since there are a lot of registrars and their user interfaces are different, I can’t show you how to do this part.

How to

1. Set up River2 so that it’s creating static files in a sub-folder of your Dropbox folder. That’s done on the Prefs page of the River2 app, and it’s linked in the menu at the top of every page on your River2 site. Follow the instructions in this earlier howto if you haven’t already set up Dropbox on your server.

2. From the Prefs page, copy the path to the folder onto the clipboard. Here’s a screen shot that shows what you’re looking for. We’re going to show the OPML Editor how to serve from that folder.

3. Bring the OPML app to the front.

4. In the Misc menu, choose the Jump command.

5. Enter this address: config.mainresponder.domains then Click on OK.

6. Press Return to create a new entry in the table. Click in the Value portion, where it says (nil), and paste in the file path you copied to the clipboard in step 2. Press Return.

7. Click in the Name portion of the new entry and replace “item #1” with the name of your domain, press Return.

When you’re done config.mainresponder.domains should look like this.

I’ve set it up so that my tester server is generating a public version accessible at daveriver.reallysimple.org. If that URL doesn’t work, it means that I’ve retired the test server.

Also note, as of this writing there isn’t really an alternative to Dropbox. If there is one at some time in the future, of course you can use it. And technically, you don’t actually have to use Dropbox for this feature to work. However it doesn’t interfere with Dropbox if you are already using it (and it’s a very cool way to connect servers and workstations).

How to export your River2 subscription list

Donovan Watts asks: “Can you tell me how to export my River2 feeds? Installing River2 on my Mini & can’t figure out how to transfer feeds from laptop.”

1. From the River2 home page, click on FEEDS in the menu at the top of the screen. Scroll to the bottom of the page, where you should see a link that says: “View the OPML subscription list.” Click the link.

2. The OPML file appears in your web browser. Then choose Save Page As from the File menu of your browser (I use Firefox or Chrome, the command might have a different name in other browsers). Enter the name of a file and click Save.

3. Then, to import the OPML file into your installation, bring the OPML app to the front and choose Import OPML from the River2 sub-menu of the Tools menu. Locate the file you exported in step 2.

Note: I like to answer questions in blog posts instead of on Twitter because I get more than 140 characters to explain what’s going on. Also it’s easier for people to find an answer using a search engine, in the future. It often works better if you can ask the question in an environment which doesn’t have a 140-character limit. People often omit an essential piece of info in their request for info, and it’s even worse with the 140-character limit. If you can’t find a blog to post your question on, just post a comment here.

Matt’s questions about River2

Matt Diaz is an incoming Studio 20 student and has been using River2. He had some questions — which I am answering here on the blog in case these come up for others.

1. He’d like to be able to organize the feed he’s subscribed to into separate streams that River2 saves into separate HTML files and pushed to Dropbox.

There is a way to do this, it works, but there’s no user interface to set it up. I use the feature on the east-village.org server, I have a stream for the East Village blogs, one for nyblogs.org and another for my own personal aggregator with the news feeds I’m interested in.

I think it’s a little too difficult right now to hack it in yourself. I need to create a UI that makes it possible to create new users for a River2 installation. Just know that it’s not too far from being real, and if you really want it, bring your laptop to the next meetup and I’ll see if I can get it to work manually.

2. He’d like to get rid of the small notice of news that right now is advertising nyblogs.org.

That’s totally cool. I could add a pref to turn it off, but in the meantime you could change the CSS for the site to shrink it down to 0 pixels. Open river.css in the River2 sub-folder of the OPML folder, and look for “caption.” That’s where you go to change the style of the caption. Just save it, and the next time the page is rendered it’ll use the new stylesheet.

3. He writes: “I was hoping you could clarify how items are organized on the River2 main page. The way I think it works is that items are displayed with the newest ones closest to the top. Then, if River2 pulls an item from a feed that has published another item recently, River2 lumps all of them together (with the newest item at the bottom), and puts the lump at the top of the main page. Does this sound right?”

That’s pretty close. Every hour River2 does a scan. For each feed it reads, it pushes all the new items from that feed onto the home page, at the top of the page. Then it checks the next feed, until it’s read all of them. It groups them this way so it’s easy to see what’s new, and then easy to associate each new item with the feed it came from.

JavaScript includes in River2

See the earlier piece for a tutorial on what JavaScript includes are and how they work.

Today there’s a new feature in River2. If you have the Dropbox feature turned on, in addition of generating a static HTML page, River2 will also generate a JavaScript include file (index.js) and an OPML subscription list (index.opml) in the same folder as the HTML file. The screen shot below illustrates:

A picture named dbfolder.gif

The OPML subscription list, index.opml, is of obvious value — it makes it possible to share your list with other users. It also backs up your list in a place that’s automatically synched with your other computers.

The JavaScript include file, index.js, file lets you include the result of the aggregator in another website. We’re going to use it as part of the nyblogs.org project to include the news in a WordPress weblog.

For an example of how it works, do a View Source on this page:


There are basically two moving parts — the stylesheet and the <script> that includes the .js file.

If you look in the stylesheet, you’ll see it defines styles specifically for River2. You can either copy the contents of the stylesheet, or if you have CSS skills, you can customize the look of the river when it appears in your site.

How JavaScript includes work

I’ve long felt that HTML should have an “include file” mechanism similar to the one that many programming languages have. When I lobbied for it in the early days of the web, the people at Netscape and Microsoft said they feared it would we abused. I didn’t think that was much of an argument because people were copying HTML anyway. View-source was one of the best things about the web. If you wanted to understand how something worked, it was always just a matter of looking to see how they did it.

Finally they relented, or maybe it was just an accident, a door they forgot to close, because with JavaScript they gave us the ability to incude a script within a page. And a script can generate text. So you just have to come up with a way to turn your HTML text into a script. It’s a very simple thing, even though it seems like an unnecessary step — you can automate it so it’s not a big deal.

I wanted to show the members of the Thursday evening group how this works, because we’re going to use this technique in nyblogs.org, to allow us to include the result of the aggregator inside a WordPress blog. But first a simpler example.

Create a text file on your hard disk, and call it test.html. Add this code to the file:

<html><body><script type="text/javascript" src="http://static.newsriver.org/afp/js/randomThumb.js"></script></body></html>

Save it, then drag the file’s icon onto Firefox (or whatever browser you use) and you should see an image on the page. If you click the image it’ll take you to the full version of the page. And if you wait a few minutes and refresh the page, the image will be different.

This is how the random image in the right margin on scripting.com is implemented.

I have a process on one of my servers that generates the randomThumb.js file and puts it in the same place every time. Try entering the URL of the script into the address bar of your browser.


And do a View Source.

You’ll see a “document.write” statement, and inside it — a bit of HTML. That’s the extra step I had to do to make this work. Instead of HTML code, the file contains JavaScript code, and it in turn generates the HTML we want to appear in the page. Convoluted, but it works. (This is what programmers call a klooge.)

River2 might need a manual update

My main River2 installation stopped finding new stuff a couple of days ago, and in the rush of iPad mania, I didn’t get to look into it right away.

The problem was caused by an update I released on March 30 that was part of a major overhaul that makes River2 a multi-user product. (There’s still more work to do on this.)

River2 should automatically update overnight, so if you leave it running, the fix that I just released should take care of any problems. However if you’re not leaving it running, or if you want the fix immediately, here’s what you can do.

1. Bring the OPML app to the front.

2. Choose river2.root from the Window menu.

3. Choose Update front tool from the Tools menu.

4. Click OK to confirm.

If you needed the update you should get one new or updated part.

Instapaper + Dropbox + River2 = Coolness

Elasticthreads, the guy who asked for both Instapaper support and Dropbox support in River2, now asks that the two features be combined. An obvious desirable thing. And if you update river2.root, you can have the feature now.


Here’s my Dropbox-based river, with Instapaper icons. :-)

How to update

1. Launch the OPML Editor.

2. Bring river2.root to the front.

3. Choose Update Front Tool from the Tools menu.

4. Click OK to the confirmation.

How to use

First, be sure that the Dropbox feature is enabled.

Second, be sure the Instapaper feature is also enabled.

Then if you view your River you’ll see that there are now Instapaper icons next to most items. If you click an icon, you are transported to the Instapaper site, where it confirms your username and password. Click on OK and then the story is added to your list of unread items. Click the Back button in your browser a couple of times to get back to reading your river.

Being sure you’re up to date

If for some reason you believe you haven’t got a fully up-to-date copy of River2, here’s how you can be sure you’re fully updated.

1. Launch the OPML editor.

2. Choose Update opml.root from the File menu. Click OK to confirm.

3. Choose Tool Catalog from the Misc menu. Click on the Install link (shown in the screen shot below).

A picture named installRiverCatalog.gif

4. Click OK to confirm you want to install river2.root.