Tube Archivist v0.6.0, published 25 October, makes a structural change it describes as security work: “This release improves security by allowing Tube Archivist to run under a dedicated, non-root user, reducing the application’s privileges.”

The way it bought that is the part that lands on operators. “To support this, the bundled nginx server has been removed. All media and artwork are now served directly by the application.” One process fewer, one privilege level lower, and a set of paths and settings that no longer behave as they did.

The release says so without dressing it up: “There are breaking changes. Read the migration guide before updating.” What follows is that guide, in its own order, because the order is the useful part.

Container user and file ownership

First, “Remove HOST_UID and HOST_GID from your environment variables.” Ownership is no longer something the application manages for you.

If you want the non-root behaviour, the guide’s second step: “To run Tube Archivist under a dedicated user, set user: "1000:1000" on the tubearchivist service in Docker Compose, replacing these values with your UID and GID.”

Third, and this is the one that bites if skipped: “Before starting the container under that user, change ownership of the cache and media mountpoints, including their contents, to match.” The release gives two example commands, run on the host, and says to replace the paths and UID/GID with your own:

sudo chown -R 1000:1000 /path/to/cache
sudo chown -R 1000:1000 /path/to/youtube

The guide is explicit that this is a choice, not a requirement: “Setting a user is optional. Without it, the container continues to run as root. Tube Archivist no longer changes file ownership itself.” So the security improvement is available rather than imposed. What is not optional is the consequence of the last sentence: whatever user you choose, the files have to be owned by it before the container starts.

Port, and the URLs that moved

TA_BACKEND_PORT is retired: “Remove TA_BACKEND_PORT if you have set it.” The replacement is “Use TA_PORT to override the container’s listening port. The default remains 8000”, and “If you change TA_PORT, update your Docker port mapping and any reverse proxy configuration to match.”

Then the quiet one: “Video, subtitle and artwork URLs have changed. If you use saved direct links, custom integrations or reverse proxy rules for these paths, update them to use the URLs returned by the API.” Anything that hard-coded the old media paths, including proxy rules outside Tube Archivist, is a candidate here.

Older installs have a step before this one

“Update older installations to v0.5.12 and let startup complete before moving to v0.6.0.” The same section notes “Migration steps for releases before v0.5.5 have been removed”, so a very old install cannot jump straight here.

Elasticsearch goes from 8.19.0 to 9.5.5

The update path, in the release’s words, “is from 8.19.0 to 9.5.5”. If you use bbilly1/tubearchivist-es, the guide says to update it together with Tube Archivist. If you use another Elasticsearch image and are still on an older 8.x version, “update to 8.19.x first before moving to 9.x”, which makes the database the second two-step part of this upgrade.

One more trap is documented because people followed earlier instructions: if you used the previous Kibana setup in CONTRIBUTING.md, you may see Error opening log file 'logs/gc.log': No such file or directory. The release’s fix is four steps: stop the containers, remove the unnecessary Elasticsearch config volume mount, start them again, and recreate the Kibana token using the updated instructions.

If it goes wrong early

There is an exit, and the release names its shape: “If you are not yet ready, you can revert to v0.5.12 once you see the startup error, no state will have changed at that point.” That is a narrow window by design: it applies when startup fails before anything has been migrated, not after the app has been running on the new version.

What else is in the release

The fixes are the sort that accumulate in an archiver: nginx access logs no longer grow inside the container, because nginx is gone (#1202); Fast Add items stop making unnecessary thumbnail requests and logging 404s (#1195); manual imports fall back to local metadata when YouTube is unavailable or rejects the request, including private videos and bot-detection errors (#1133); pagination near the 10,000-result limit is fixed for certain page sizes (#746). Subtitles get several repairs, including existing subtitles no longer being lost when a reindex cannot fetch replacements. Playlist thumbnails now use the first video’s thumbnail, and snapshot settings now take effect when toggled and at startup.

Who should wait

If your Elasticsearch is still on an older 8.x image, or your install predates v0.5.5, this is a two-step upgrade before it is a one-step one, and the first step is v0.5.12 finishing startup. If you are current, the work is a session of reading, a chown and a proxy check, in that order.

Sources: the Tube Archivist v0.6.0 release record and the rendered release page.