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 Docker.com to install Docker Engine on the Ubuntu server
Step 2: Confirm you have Docker running by entering sudo docker run hello-world
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 192.168.142.129 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 http://192.168.142.129:1337
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
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.