Don't just restart the NAS Docker container—five steps to upgrade without losing data

A
yellow bar popped up in the Jellyfin backend corner, so I clicked 'Restart' on the container. Ten minutes later, I checked the settings and found the version number hadn't changed at all. At that moment, I was puzzled—even after rebooting, why couldn't I get promoted? Later, I realized that restarting the container means bringing the same food box down and back up, with the same old dish as before. This article will go through the container upgrade process from start to finish: how to copy parameters, how to pull images, why data won't be lost—all explained clearly.
Let's figure this out first: a restart is a reboot, an upgrade is an upgrade
When I wrote about getting started with Docker before, I gave an analogy: image is the installation package, and the container is the program that runs with the installation package. When it comes to leveling up, the bottleneck lies in this relationship.
You click 'Restart'—whether it's the router or the NAS, all they do is shut down the current container and reopen it, still using the old image from the hard drive. When the developer releases a new version, it's like making a new installation package. If you don't pull it down, even if you restart a hundred times, it's still the old version. So the real upgrade is: pull a new image, delete the old container, and start a new one with the new image based on the original parameters.
The first time I understood this process, my instinctive reaction was, "So what do I need to refill if the containers aren't fully configured?" —This is the most common misunderstanding for beginners. Configurations and data shouldn't be stored in containers at all. The "directory mount" done when installing containers means connecting folders on the NAS hard drive into the container as its data directory. The container can be deleted or rebuilt at will, and nothing on the external hard drive remains untouched. As long as you do the right mounting at the start, the process of changing the lunch box won't damage a single dish.
Conversely, if a container never had a configuration directory installed, upgrading is a complete reset. I suffered this early time installing downloaders—two months of download records vanished in no time. This happened I've written lessons and won't repeat them. Before upgrading, take a look at the mount list—it's more important than anything else.
Before starting, do only one thing: copy down the parameters
Before deleting a container, there are three things you must copy completely; missing one means losing one function after rebuilding:
| What to copy | ,what to watch when copying |
|---|---|
| Port mapping | : the left side is the NAS port facing outside, the right side is the port inside the container. Don't copy left or right. |
| the directory | has two column paths: the left is the real NAS path, the right is the internal container path, each cell matching | one by one
| Some containers | rely on it to pass passwords and parameters without missing a single line |
My Flying Cow, go to the container detail page, just copy these items page by page, and if you find handwriting too slow, just screenshot them. Helping my cousin with Synology was much easier. In Container Manager, you can access container details, and ports, mounts, and environment variables are all on the same screen. When rebuilding, the wizard still remembers the last configuration, basically following the next steps.
There are shortcuts for using the command line: SSH enters the NAS and types a docker inspect container name, then outputs all the parameters at once, redirecting them to a text file and storing them. How to start SSH written about this before, so it won't be expanded here.
Upgrade in five steps
The logic makes sense. The movement is actually just five steps, and I followed this order for two years
| What | are the steps | to make mistakes |
|---|---|---|
| Step one | :copy the parameter | screenshot and save it, don't rely on memory |
| Step two | : whenrecruiting a new image | ,make sure the tag matches the original, see below |
| Step three: | Deactivate and delete the old container. | Deleting the old container means deletion, not stopping. If you stop, the new container won't start |
| Step four: | copy parameters and rebuild | the mounting path. Check column by column to avoid serial checks |
| Step five | :Go to the backend to check the version number | The upgrade is only considered complete when the version changes |
The second labeling is the easiest to fool people. When installing containers, it was recommended not to use latest if you could lock the specific version number. This way, you need to do one more step during the upgrade: change the image label from the old version to the new version and then pull it. For example, if the original version was 2.5.0 and the official releases 2.6.0, you just pull it to 2.6.0. Using Latest is easier—just reload the Latest and it's new—the price is when the version changes and what it looks like, it's entirely up to you.
Take my QBittorrent example: upgrading from 4.5 series to 4.6.1 was because the temporary password mechanism changed from 4.6.1 onward. The default adminadmin password was removed, and the random password for each startup is printed in the container log. After upgrading, go to the container log and flip through the line "A temporary password," copy down the new password, and then change it. The process is completely closed. This downloader is a complete guide from installation to preservation in the downloader section.
Containers installed with Compose are the most comfortable. A Docker Compose Pull pulls down a new image, then Docker Compose up -D. Stopping and creating old containers and new ones is fully automatic. All parameters lie in the configuration file, so there's no need to copy at all. I now use Compose for all new containers, which is a lesson learned from the upgrade experience.
My hands are shaking a lot, so I took a snapshot of the shared folder I mounted before rebuilding. Snapshots are a feature only available in the Btrfs file system; the ext4 drive does not. How to choose between the two file systems I wrote an article about it.
Not being able to move the mirror is the most common obstacle on the upgrade journey
The second step
is the easiest to get stuck on in the five steps. Docker's mirror repository fluctuates between direct connections in China. The old public acceleration addresses circulating online, the USTC batch and the early DaoCloud era, mostly stopped or throttled. Copying old tutorials is almost futile.
The most reliable approach I've tried over the past two years: register an Alibaba Cloud account, log in to the console, find the 'Mirror Accelerator' page in the 'Container Image Service,' and you'll be sent a dedicated address formatted https:// your ID.mirror.aliyuncs.com. Just assign this address to the NAS's Docker settings—Feiniu's Docker settings have an entry to the image source, click a few times on the graphical interface; Use the command line to change /etc/docker/daemon.json, add this address in registry-mirrors, and restart the Docker service to take effect. Personal addresses are free, which is much more practical than relying on luck to find public sources.
There's another silly method that works forever. When my home had a short-circuit broadband, I relied on it to help: find a computer that can run (or the phone's hotspot) to pull down the image, export the image name with docker save -o filename .tar image name as a file, transfer it to the NAS with docker load -i filename.tar import it in, and then rebuild the old container and rebuild as usual. The file size is larger; a Jellyfin image exports is about 1GB smaller, but it doesn't have to worry about network usage.
Just a reminder: during those few minutes of mirroring, the hard drive is writing. Don't schedule scheduled auto-update tasks at midnight when the hard drive should be hibernating. I've written an entire article about troubleshooting hard drives woken up by stolen drives. Don't plant this for yourself.
If you don't clean after leveling up, the old mirror can take up the storage pool
The hidden part of
this is that every time you level up, the old mirror remains in place and won't be automatically deleted. What you deleted was a container, and the "old installation package" was still lying on the hard drive. Upgrading seven or eight times a year means one container can save several GB of old versions.
Last time I cleared the storage pool, I specifically checked the accounts, Docker took up over forty GB. Aside from container logs, more than half were old images accumulated from previous upgrades. The cleaning method is not complicated: a single docker image plug from the command line can wipe out images without containers; For those that don't touch the command line, sort them by size in the image list, and remove those labels that show none—those are the older versions replaced after the upgrade.
Before deleting, check the container list to confirm that the image you want to delete has no containers running. The cleanup should only touch unused items. After clearing these forty GB, you can recover more than half, which is much better than deleting photo cache.
Watchtower updates automatically, I only let it manage two containers
If you move
smoothly in five steps, some people will find it annoying. There's a container called Watchtower (image name containrrr/watchtower) that specializes in this: it installs itself as a container, regularly scans other containers on your machine, and when it finds a new version of the image, it automatically pulls the new image, shuts down the old container, and rebuilds it with the original parameters—you don't have to worry about the whole process.
It sounds beautiful, but my choice is to hand over the stateless container to it. For things like the video library and downloader, just restart if they fail. The data is all outside, so if it upgrades automatically, then just upgrade it. All containers with databases are manual—apps like albums are connected to the database, and when the version jumps, the database structure changes. If the auto-upgrade crashes in the middle of the night, you only realize the next day that the Photos app can't connect to the database, and those few hours of backup are in jeopardy. When manually upgrading database containers, make sure the backup runs for the same day before uploading. This habit is more valuable than any automation.
My specific usage is to create a Watchtower container by clicking only two names, letting it focus on Jellyfin and Navidrome, < a href="https://www.shunot.com/en/nas/1104.html"> the video library and music server These are things that can be restarted in a minute if broken, so leave them to them with peace of mind. Set the time in broad daylight, don't secretly write in the middle of the night.
Finish by pinning down the order: check update announcements, copy parameters, take snapshots, pull images, delete old containers and rebuild, go to the backend to verify version numbers, and clean old images. And one more thing: don't mix things up—container upgrades and NAS system updates are two different things. The system update button has its own rules, My experience of delaying clicking it for three months is in this article. If you're just starting out, you can start with the complete Docker beginner's guide to the basics before experimenting with upgrading the set.
