The following recipe assumes the reader is familiar with Docker, knows how to create images and containers, and has an account on Docker Hub. Familiarity with Git is helpful if you want to use Github to obtain and get updates to the source files, but it is not required. I am also assuming that you are executing these instructions on a computer running some form of Unix.
I recommend following the instructions in Docker Docs to install Docker Engine on the computer that will host your River4 container. For reference, I used Ubuntu server, running as a guest in VMWare workstation on a computer running Windows 7 to create my image of River4. I've tested the image I created using Kitematic on Windows and OS X and I have used Boot2Docker on OS X. Kitematic appears to provide the easiest way to run Docker on a Windows or Mac computer.
Step 1, Obtain Source files
Obtain the River4 source files from the River4 Github repository. You can either use Git to obtain a copy or click the Download Zip button on the repository web page. Create a directory on the computer that has Docker installed and extract the Zip file to that directory. To use Git, CD to the directory you created to store the River4 files and enter git clone https://github.com/scripting/river4.git
Obtain the Dockerized River4 source files from the Github repository. You can either use Git to obtain a copy or click the Download Zip button on the repository web page. Create a directory on the computer that has Docker installed and extract the Zip file to that directory. To use Git, CD to the directory you created to store and enter git clone https://github.com/fmcpherson/DockerizedRiver4.git
Note that, if you are using git to obtain the source files, it is best to create separate directories for the River4 and Dockerized River4 files so to not confuse git. If you simple download the Zip files, you can extract the files into one directory.
Step 2, Package together the Docker Image source files
Create a new directory
Copy the River4 source files to that directory.
Copy the DockerizedRiver4 source files to that directory
After you complete step 2 your directory must have the following files, if any of these files are missing you will successfully create your Docker image.
Dockerfile
SampleSubscriptions.opml
river4.js
package.json
Your directory may contain additional files, but the ones above are critical to building an image that will run River4. Next, we will create the river4data directory structure. While we River4.js will create these directories if they do not exist, we need to create them so that the SampleSubscriptions.opml file is in a location River4.js expects in order to look for news articles.
Step 3, Create river4data directory structure
Make sure you are in the directory that you created for step 2
Create river4data by entering mkdir river4data
Change to the river4data by entering cd river4data
Create the following directories: data, lists, and rivers by entering the following
mkdir data
mkdir lists
mkdir rivers
The next step is to copy a OPML file to the /river4data/lists/ directory. This file will contain your subscriptions list. I recommend you use SampleSubscriptions.opml, which you copied in Step 2.
Step 4, Copy SampleSubscriptions.opml to /river4data/lists/
Return to the directory that contains the files you packaged together in Step 2. For example, if the folder you created in Step2 is named river 4, enter cd ~/river4
Enter cp SampleSubscriptions.opml ./river4data/lists/
At this point you have all the files placed in their correct locations and you are ready to build your Docker image for River4. The instructions to build the image are contained in Dockerfile, which is in the directory you created in Step 2. You must execute the commands from within that directory.
Step 5, Build your River4 Docker image
If you think you will want to share your River4 Docker image, you will want to create an account on Docker Hub, and you will then use the account name as part of the image name. For example, my account on Docker Hub is fmcpherson and therefore the name for my River4 image is fmcpherson/river4.
The command to build a Docker image is: docker build -t [image name] .
For example, the command that I execute is docker build -t fmcpherson/river 4 .
Note that the space and period at the end of the command is important, it indicates that the current directory contains the source files for the image. Again, be sure that Dockerfile is in the current directory as it provides the instructions for the docker build.
If all goes well, your River4 Docker image will be built and added to the list of images on your computer. If you enter docker images you should see your River4 image listed. At this point y0u have successfully created your Docker River4 image.
Run Your River4 Image
To run your River4 image, enter docker run --name river4 -d -p 1337:1337 [image name] for example, the command that I enter to run my River4 image is docker run --name river4 -d -p 1337:1337 fmcpherson/river4.
Here is a brief explanation for the run command:
--name provides a name for the container, if you don't provide this Docker will automatically create one.
-d specifies to run the container in the background. If you are familiar with it, this is similar to the forever utility.
-p maps external network ports to internal network ports, in the format external port : internal port. The internal port 1337 is the port that River4 is listening to, the external port specifies which port an external computer uses to communicate with the container. For example, to open your river you can enter localhost:1337 in the address bar in your web browser.
To confirm that your container is running you can use the docker logs command to see the River4 console output. Enter docker logs river4, assuming you named your container as in my example above.
At this point, River4 is running in a Docker container on your computer. You can open a web browser, enter localhost:1337 in the address bar, and the River4 home page will load and over time it will display the title of news articles obtained from the sites in your reading list. Note that if you are running the container in a virtual machine on your computer you will need to enter the IP address for the virtual machine and not use localhost. There may be a variety of reasons why y0u cannot access the River4 site if it is host3ed in a virtual machine, and troubleshooting them is beyond the scope of this article. The most likely cause of any access problems with virtual machines is that the networking is not properly set up for the virtual machine.
If you use Kitematic to run the River4 container it will display the ip address and port number that you need to enter in the web browser address bar to open the River4 home page.
To Stop Your River4 Container