Example project

In this example, every device in a project serves a web page you write. You try it on one device, roll it out to the rest, change the page, then let CI deploy each change for you. It builds on Deploy your first app.

Before you begin

• A project with a few devices that show as Online. This example calls the project my-fleet and one of its devices lab-pi; use your own names.
• The Suta CLI, signed in with suta auth login, with a role that can deploy software, such as Operator.

Set up the project

1. Create a directory for the project, and go to it:

   mkdir my-fleet && cd my-fleet

2. Create index.html, the page each device serves:

   index.html

   <h1>Hello from Suta</h1>

3. Create suta.yaml:

   suta.yaml

   # yaml-language-server: $schema=https://suta.dev/schema/suta.json
   project: my-fleet
   os: latest
   
   apps:
     web:
       image: nginx:1.27
       ports: ["8080:80"]
       files:
         /usr/share/nginx/html/index.html:
           source: index.html
       probe:
         http: /
         port: 80

files puts your index.html where nginx serves it from. The probe checks that the page loads; a device keeps a change only if it passes for the whole probation.

Try it on one device

1. Plan for one device only:

   suta plan --device lab-pi

   + lab-pi · update to 5d1e07a9c2b4
       OS 2026.09.4
       Apps: + web
   
   Plan: 1 to update, 0 unchanged, 0 pinned.
   
   Plan 2b7f…
   Deploy it with suta deploy 2b7f…

2. Deploy that plan, using the plan ID from the output:

   suta deploy PLAN_ID --wait

3. Open http://DEVICE_ADDRESS:8080 in a browser on the same network. You see Hello from Suta. The device’s address is on its Overview tab in the dashboard, under Connection.

Roll out to every device

suta deploy --wait

suta deploy shows the plan and asks you to confirm. lab-pi is already up to date, so it’s listed as = unchanged. With five or more devices, one goes first on its own; the rest follow ten at a time, each wave only after the one before has succeeded. If a device fails, the rollout pauses and that device goes back to what it ran before. See Plan and roll out.

Change the page

1. Edit index.html:

   index.html

   <h1>Hello again from Suta</h1>

2. Plan and deploy:

   suta deploy --wait

   Each device lists Apps: ~ web: only the web app changes.

3. Refresh the page in your browser to see the new text.

Deploy from CI

Commit the project, including suta.lock, which pins the exact image the plan used:

• Directorymy-fleet/

  • .github/workflows/deploy.yml
  • index.html
  • suta.yaml
  • suta.lock

Then let GitHub Actions deploy every change to main:

1. Create an API token with the Operator role, and save it as a repository secret named SUTA_TOKEN.

2. Add a workflow:

   .github/workflows/deploy.yml

   name: Deploy
   on:
     push:
       branches: [main]
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Install the Suta CLI
           run: |
             curl -fsSL https://suta.dev/install.sh | bash -s -- --cli
             echo "$HOME/.local/bin" >> "$GITHUB_PATH"
         - name: Deploy
           run: suta deploy --yes --wait
           env:
             SUTA_TOKEN: ${{ secrets.SUTA_TOKEN }}

Now editing index.html and pushing to main updates every device. The job fails if any device rolls back, so a broken change shows up as a failed check.

Next steps

• Write suta.yaml to add secrets, volumes and settings per site.
• Set up alerts for failed deploys and devices that go offline.