A Step-by-Step Guide to Updating FreshRSS in a Docker Container

https://xpil.eu/xvns

There's an old saying, "If it ain't broke, don't fix it." But let's be honest, that's terrible advice in the tech world, especially when it comes to updating your software.

I use FreshRSS to keep up to date with over 250 blogs I subscribe to. They publish a new version every now and then, and it simply makes sense to update as soon as it comes out - especially since they do not guarantee a smooth update process if you skip a version. In my case, I took a risk and updated from 1.19 to 1.21 - fortunately, it worked.

This guide will walk you through the process of updating your FreshRSS Docker container step by step.

Note: my personal setup is based on a home NAS (an old 4-bay Synology device) but in theory it should work with any Linux distribution with FreshRSS Docker-based installation.

Note: I'm wary of updating any Docker-based systems as I know very little about Docker itself, and Murphy's Law works against me. Any update I try to run usually ends up in a data loss or at least a system instability. This article shows that one time it worked for me (almost) with no issues 🙂

Prerequisites

Terminal access to the system running your FreshRSS Docker container
Root (or equivalent) access

Step 1: Backup Your FreshRSS Data

Before making any changes, back up your FreshRSS data to safeguard against potential data loss.

cd /path/to/your/backup/folder
tar -zcvf freshrss_backup.tar.gz /path/to/freshrss/data

Note: if you do not know the path to your FreshRSS data, run docker ps -a first to find out the name of your Docker image (it will likely be in the last column of the relevant entry - the default is freshrss which I am using here), then run the docker inspect freshrss command, finally locate the "Mounts" section and look for "source" there.

Step 2: Identify the Current FreshRSS Version

To know what version you're currently running, use the following Docker command:

docker inspect freshrss | grep "org.opencontainers.image.version"

Step 3: Pull the Latest Image

Pull the latest FreshRSS Docker image.

docker pull ghcr.io/linuxserver/freshrss

Step 4: Stop the Existing Container

Before replacing the container, we need to stop it.

docker stop freshrss_container_name

Step 5: Rename the Old Container

If you'd like to keep the old container, rename it; otherwise, delete it. I am careful so I went with the former (also: see step 8 below)

docker rename freshrss freshrss_old

Step 6: Run the New Container

Run the new FreshRSS Docker container.

docker run --name=freshrss -p 9009:80 -v /path/to/freshrss/data:/config -d ghcr.io/linuxserver/freshrss

Note: my local setup includes a redirection on the router, so that the instance is reachable from the outside. The above command assumes you are using default port number (9009) - I have a port redirection on my router, going from public TCP 9009 to (my NAS IP address):9009

Step 7: Verify

After running the new container, check its status by opening the instance as usual (in your browser). If everything works, you are done.

In my case, I got a scary 502 nginx error and I had to fix my configs:

Step 8: Troubleshooting

If you encounter a 502 Bad Gateway error, copying the config files from the old instance may help (it worked for me, but YMMV).

Start with retrieving old and new instance image IDs (assuming you did not delete your image in step 5). In order to do so, run:

docker ps -a

Take a note of both old and new instance identifiers (12-character hex strings). Then run:

docker cp 0123456789ab:/config/nginx/nginx.conf ./nginx.conf.old
docker cp 0123456789ab:/config/nginx/site-confs/default.conf ./default.conf.old
docker cp ./nginx.conf.old abcdef012345:/config/nginx/nginx.conf
docker cp ./default.conf.old abcdef012345:/config/nginx/site-confs/default.conf

Note: in the example above, remember to replace 0123456789ab with the id of your old container, and abcdef012345 with the new one.

And there you have it!

Updating FreshRSS within Docker is not too complex but it has its quirks; I hope you find this article helpful. Feel free to leave a comment.