How do you upgrade and update the NAS Docker container? Restart doesn't work; after completing the five-step process, you won't lose any data
Jellyfin the backend corner, a yellow bar popped up saying "New version available." I casually clicked restart on the container, and after ten minutes, 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 container means bringing the same food box down and back up, and the dishes are still the same old . 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.
first think about this: a restart is a reboot, an upgrade is an upgrade
when I wrote about getting started with Docker, I gave an analogy: images are 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 NAS, all they do is shut down the current container and restart 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 use the new image to create a new with the original parameters.
I understood this process for the first time, my instinctive reaction was, "Then what are the incomplete configurations in my container? Do I need to refill them?" —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 it is a complete reset. I suffered this loss when installing downloaders early on—my download records disappeared in two months. I've written lessons about this won't repeat it. Before upgrading, take a look at the mount list—it's more important than anything else.
do one thing before starting: 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 you need to copy | what do you watch when copying |
| Port mapping | left side is the NAS port facing outside, the right side is the port inside the container. Don't copy left or right |
| mount directory | two rows of paths: the real NAS path on the left, the internal container path on the right, each cell |
| environment variables | some containers pass passwords and parameters without missing a single line |
my Flying Ox, go to the container detail page, copy these items page by page, if you find it slow to copy, 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's a shortcut to the command line: enter the NAS with SSH, type a docker inspect container name , then throw out all the parameters at once and redirect them to a text file for storage. How to start SSH previously written about, so I won't elaborate here.
five steps to complete one upgrade
the logic makes sense—the movement is actually just five steps, and I followed this order for two years:
| steps | what to do | points prone to failure |
| Step one | copy parameters | take screenshots for backup, don't rely on memory |
| Step 2 | Bring in new images | tags must match the original, see below |
| Step 3 | Deactivate and delete the old container | deleting it, not stopping. If you stop, the new container won't start |
| Step 4 | copy parameters to rebuild | check the mounting path column by column, don't serialize it |
| Step 5 | go to the backend to check the version number | only when the version changes does the upgrade count |
the second step labels are the easiest to fool people. When installing containers, it's recommended not to use latest if you can lock the specific version number after . This way, when upgrading, do one more thing: change the image tag 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 as an example: upgrading from 4.5 series to 4.6.1 was because the temporary password mechanism changed from 4.6.1. 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. The complete pitfalls from installation to seed preservation this downloader are in the downloader section.
containers installed with Compose are the most comfortable. One docker Compose pull pull down the new image, then docker Compose Up -d. Stopping and creating old containers and creating new ones is fully automatic. All parameters lie in the configuration file, so you don't have to copy them at all. I now use Compose for all new containers, which is a lesson learned from the upgrade experience.
my hands are shaking, take 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 .
unable to remove the mirror is the most common obstacle on the upgrade journey
Among the five steps
, the second step is the easiest to get stuck. 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 path 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 it will send you a dedicated address formatted as 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 broadband system running out, I relied on it to help: find a computer that can run (or the phone's hotspot) to pull down the image, export docker save -o filename .tar image name export it as a file, transfer it to the NASdocker load -i filename .tar_ and import it in. The rear is to discard old containers and rebuild them as before. The file size is larger; a Jellyfin image exports is about 1GB smaller, but it doesn't have to worry about network usage.
a quick reminder: the hard drive is writing during those few minutes of mirroring. Don't schedule scheduled auto-updates at midnight when the hard drive should be hibernated. I've written an entire article about troubleshooting hard drive woken up by stolen records so don't plant this trap for yourself.
upgrade and not cleaning, old mirrors can consume the storage pool
the hidden part of this is that every time you level up, the old mirror image stays 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 that section accounted for over forty GB. Aside from container logs, more than half were old images accumulated from previous upgrades. The method is simple: a single command line docker image prune to wipe out mirrors 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 auto-update, I only let it manage two containers
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.
sounds beautiful, but my choice is to just hand over the stateless container to . 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 watch Jellyfin and Navidrome. the and music server are all things that can be restarted in one minute if they fail, so I trust them with confidence. Set the time in broad daylight, don't secretly write in the middle of the night.
Finish the order in a fixed 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 mess around—container upgrades and NAS system updates are two different things. The system update button has its own rules, my experience of delaying clicking for three months is in this article. If you're just starting out, you can start with the complete introductory guide Docker to fill in the basics, then work around to upgrade the set.
