Build a River4 Server With Docker and Ubuntu

The following instructions assume the reader has access to an Ubuntu server and is somewhat familiar with how to function within the server. To build a functioning River4 server do the following (if you are already running Docker skip to step 3):

  • Step 1: Follow the instructions provided on to install Docker Engine on the Ubuntu server

  • Step 2: Confirm you have Docker running by entering sudo docker run hello-world

    • When you finish installing Docker you will see an instruction to add your user ID to the docker group so that you don't have to prefix all the docker commands with sudo. I recommend following that instruction. If the commands that follow do not work, prefix them with sudo. You may be prompted for your password prior to the command executing.
  • Step 3: Run the River4 container by entering docker run --name river4 -d -p 1337:1337 fmcpherson/river4

    • --name provides a name to the container, making it easier to run subsequent commands

    • -d specifies to run the container in the background, similar to how forever works

    • -p specifies port mapping in the format [host computer port] : [container port]

  • Step 4: Confirm River4 is running by checking for console output by entering docker logs river4

    • You may wish to pipe the output to more for closer inspection: docker logs river4 | more

    • You should see: "River4 v0.X running on port 1337, file path == river4data/" without quotes and X representing a version number. (As of this writing the current version of River is 0.118.)

  • Step 5: If you don't already know it, find the IP address for the Ubuntu server

    • Enter ifconfig and look for inet addr: within eth0.

    • For example purposes, I will use as the IP address of the server

  • Step 6: Open the River4 home page in a web browser

    • Enter [Your server ip address]:1337 in the address bar of your web browser. For example

    • The River4 Home page should load

    • Depending on the rate at which new articles are published, you may not see new article entries for some time.

  • Step 7: Check the River4 Dashboard

    • The River4 Dashboard shows you the current server status. To view the dashboard click Stuff, Dashboard on the River4 Home page.
  • Step 8: To stop the River4 container enter docker stop river4

Extra notes:

  • To confirm what Docker images are on your server enter docker images. When you run a container, Docker first checks to see whether there is an image stored on the host computer and if there is, runs it from there. If an image for the container is not found on the local computer, Docker then searches Docker Hub for the image. The River4 image is in the fmcpherson/River4 repository on the Docker Hub.

  • To remove the image from your computer enter docker rmi -f fmcpherson/river4

  • By default all of the data files that River4 uses are stored within the container. The River4 image is built with a default RSS subscription list called readinglist.opml and it is stored in /river4data/lists. Changes to data files do not persist within the container after the container is shut down. You can map a directory on the host computer to the /river4data directory in the container by adding the -v flag to the docker run command. For example:

    • Create a river4data directory in your home folder on the host computer. For example /home/frank/river4data.

    • To map the directory you created above to the River4 container enter the docker run command as follows:

    • docker run --name river4 -v /home/frank/river4data:/river4data -d -p 1337:1337 fmcpherson/river4

    • River4 will create the data, lists, and rivers directories in your /home/frank/river4 directory and the lists directory will be empty. You will need to copy a RSS subscription list OPML file to the lists directory.

  • If you are running your Ubuntu server in a public cloud, you may need to open port 1337 to access the River4 home page. The -p flag in the docker run statement specifies the port mapping in the following format [host computer port] : [container port]. The container port will always be 1337, but the host computer port can be whatever port you specify. For example to enable the River4 container to hear on port 80 enter -p 80:1337 in the docker run command. If you map port 80 you will not need to include that port number for the address to the River4 home page.

  • If you are interested in how the Docker image was built, you can look at the Dockerfile in my Github repository for the container.

Last built: Wed, Feb 17, 2016 at 3:26 PM

By Frank McPherson, Wednesday, August 19, 2015 at 1:14 PM. It's even worse than it appears.