Skip to content
SutaSutaSuta Docs

Move a device to Suta OS

On Raspberry Pi OS, Suta deploys your apps but leaves the operating system alone. Moving a device to Suta OS lets later deploys update the OS too, and roll it back if a new version doesn’t start. The move happens on the same SD card, over the network, so you don’t need to visit the device.

Before you begin

Section titled “Before you begin”
  • The device is a Pi 5, Pi 4, Pi 500, Pi 400, Compute Module 5 or Compute Module 4. The Pi 3 and Pi Zero 2 W can’t move to Suta OS yet.
  • The device runs a generation from suta deploy. The move installs the Suta OS version that generation names. If you haven’t deployed to the device yet, deploy a suta.yaml that contains only os: latest.
  • You have the Deploy software permission.
  • Move any services you still need from Raspberry Pi OS into containers in suta.yaml. See What carries over.

The device checks that it has room for Suta OS before it downloads anything, and reports if there isn’t enough.

Move the device

Section titled “Move the device”

  1. Run:

    Terminal window
    suta migrate DEVICE

    Or open the device’s Software tab and select Migrate to Suta OS.

  2. Follow the progress:

    Terminal window
    suta device generations DEVICE

    The device downloads Suta OS and prepares it, then restarts into it once as a trial.

  3. If your apps stay healthy and the device keeps reaching Suta for the whole probation, the device accepts Suta OS and starts it from then on.

If Suta OS doesn’t start, your apps fail or the device can’t reach Suta, the device restarts into Raspberry Pi OS and reports the move as rolled back, with the reason. Fix the cause and run suta migrate again.

What carries over

Section titled “What carries over”
  • The device’s identity, name, tags and site.
  • Your apps, their volumes and their secrets.
  • Wi-Fi networks you saved on Raspberry Pi OS.
  • Hardware settings, such as the overlays for a display or HAT.

Nothing else from Raspberry Pi OS runs on Suta OS: packages you installed, your own services, cron jobs and files in home directories stay behind.

Go back to Raspberry Pi OS

Section titled “Go back to Raspberry Pi OS”

Raspberry Pi OS stays on the card after a successful move. To start it again, mount the card’s boot partition on another computer and copy config-raspios.txt over config.txt.