Skip to main content

🔄 Rollback & Update Troubleshooting

TunaOS uses bootc to manage your system as a container image. Every update is atomic — if something goes wrong, you can roll back to the previous deployment in one command. This guide covers the full lifecycle: update, verify, roll back, and fix boot failures.

Quick Reference​

TaskCommand
Check current statusbootc status
Apply an updatesudo bootc upgrade && sudo systemctl reboot
Roll back to previoussudo bootc rollback && sudo systemctl reboot
List all deploymentsbootc status (see the "Queue" section)
Pin to a specific imagesudo bootc switch ghcr.io/tuna-os/yellowfin@sha256:...

How Rollback Works​

Every time you update or switch images, bootc keeps the previous deployment on disk. The boot menu shows two entries:

  1. The current deployment — the system you use now
  2. The rollback target — the previous deployment

When you run bootc rollback, bootc marks the previous deployment as the next boot target. After the reboot, the old image becomes the "current" deployment, and the problematic update becomes the rollback target.

Bootc keeps the last 2 deployments by default. Bootc automatically cleans up older deployments.

Worked Example: Update, Break, Roll Back​

This section walks through a realistic scenario: you update your system, discover a regression, and roll back.

Step 1: Check Your Current State​

bootc status

Output:

● TunaOS Yellowfin GNOME (olive)
  Image: ghcr.io/tuna-os/yellowfin:gnome
   Boot: booted

Note the image digest (the @sha256:... part) — you'll compare against it later.

Step 2: Apply an Update​

sudo bootc upgrade

Bootc pulls the latest image and deploys it:

Pulling: ghcr.io/tuna-os/yellowfin:gnome
Deploying: ghcr.io/tuna-os/yellowfin:gnome@sha256:def456...

Reboot to activate:

sudo systemctl reboot

Step 3: Verify the Update​

After reboot, confirm you're on the new deployment:

bootc status
● TunaOS Yellowfin GNOME (navy)
  Image: ghcr.io/tuna-os/yellowfin:gnome@sha256:def456...
   Boot: booted (deploying)
  Queue: rollback → ghcr.io/tuna-os/yellowfin:gnome@sha256:abc123...

The "Queue" line shows the rollback target — the deployment you used before.

Step 4: Discover a Problem​

Something does not work right — a driver regression, a broken dependency, or a display issue. You decide to roll back.

Step 5: Roll Back​

sudo bootc rollback
sudo systemctl reboot

Step 6: Confirm the Rollback​

bootc status
● TunaOS Yellowfin GNOME (olive)
  Image: ghcr.io/tuna-os/yellowfin:gnome@sha256:abc123...
   Boot: booted

You're back on the previous deployment. The problematic update is now the rollback target if you ever want to try it again.

Pinning a Specific Image​

If you want to stay on a known-good version and ignore future updates, pin to a specific digest:

# Find the digest of the image you want
skopeo inspect docker://ghcr.io/tuna-os/yellowfin:gnome | jq '.Digest'

# Pin to that exact image
sudo bootc switch ghcr.io/tuna-os/yellowfin@sha256:abc123...
sudo systemctl reboot

To resume normal updates at a later time, switch back to the tag:

sudo bootc switch ghcr.io/tuna-os/yellowfin:gnome

Troubleshooting Boot Failures​

If your system won't boot after an update, you have several recovery options.

Option 1: Select Previous Deployment at Boot​

When the system boots, the systemd-boot menu shows the available deployments. Use the arrow keys to select the previous entry and press Enter. This boots into the rollback target without any commands.

Option 2: Boot into a Live ISO​

If the boot menu itself fails:

  1. Download a TunaOS ISO from tunaos.org/download
  2. Boot from USB
  3. Mount your root filesystem and inspect logs:
# Find your root partition
lsblk

# Mount it (adjust /dev/sda3 as needed)
sudo mount /dev/sda3 /mnt

# Check bootc status from the live environment
sudo bootc status --sysroot /mnt

Option 3: Check Boot Logs​

From a good boot or rescue entry:

# View boot logs from the current session
journalctl -b -o short-monotonic

# View logs from the previous boot
journalctl -b -1 -o short-monotonic

# Check for systemd ordering cycles or failed units
journalctl -b -p err

Common Issues​

ProblemCauseFix
"Ordering cycle found" at bootA systemd unit has a circular dependencyBoot into the rollback deployment and remove the offending unit from your custom image
Black screen after bootDisplay driver or compositor issueRoll back, then check if the issue is in the new image before re-updating
Network not available after updateNetworkManager or DNS config changedRoll back, then file an issue with journalctl -b -u NetworkManager logs
Boot drops to emergency shellMissing root filesystem or broken fstabUse a live ISO to inspect /etc/fstab and the bootc deployment list
bootc upgrade fails to pullRegistry auth or network issueCheck podman pull ghcr.io/tuna-os/yellowfin:gnome first to isolate the problem

Further Reading​