Developing Akri on macOS with Raspberry Pi and Mutagen

Akri, a CNCF sandbox project, makes it easier to expose edge devices to Kubernetes clusters. However, if you’re developing Akri on macOS, you’ll quickly hit a roadblock: Akri does not build on macOS (to the date of writing this blog) due to its Linux-only dependencies.

To solve this, we’ll set up a remote development workflow using Mutagen, a fast and reliable tool for file synchronization. You’ll write code on your Mac using Neovim (or any editor of your choice), and the code will automatically sync to a Raspberry Pi, where it can be built and tested natively.


What You’ll Achieve?

  • Write code on macOS.
  • Have it automatically synced to a Raspberry Pi.
  • Build Akri using cargo build on the Pi, with updated dependencies and Cargo.lock synced in real time.

Prerequisites

  • A Raspberry Pi (running a Debian-based Linux distro).
  • Rust installed on the Pi (check Rust docs)
  • SSH access to your Pi.
  • mutagen installed on your Mac.
  • Akri repo cloned on macOS.

Step 1: Set Up SSH Access (Passwordless)

We’ll set up SSH key-based login so that mutagen can sync files without being prompted for a password.

Generate an SSH Key (if you don’t have one)

1
ssh-keygen -t ed25519

This command generates a new SSH key pair. You can press Enter to accept the default file location and leave the passphrase empty for passwordless access.


Copy the SSH public key to your Pi

The command below copies your public key to the Raspberry Pi, allowing passwordless SSH access.

1
ssh-copy-id -i ~/.ssh/id_ed25519.pub pi@<RASPBERRY_PI_IP>

Replace <RASPBERRY_PI_IP> with your Pi’s IP address.


Add a host entry

To simplify SSH access, add an entry to your ~/.ssh/config file:

1
2
3
4
5
Host akri-pi
    HostName <RASPBERRY_PI_IP>
    User gaurav
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

This allows you to SSH into your Pi using the alias akri-pi:

1
ssh akri-pi

Step 2: Clone the Akri Repository

If you haven’t already, clone the Akri repository to your macOS machine:

1
2
git clone https://github.com/project-akri/akri.git
cd akri

Step 3: Configure Mutagen

Create a Mutagen configuration file to sync your Akri code to the Raspberry Pi. Create a file named mutagen.yml in the root of your Akri repository with the following content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
sync:
  defaults:
    flushOnCreate: true
    ignore:
      vcs: true
  code:
    alpha: "."
    beta: "akri-pi:/home/gaurav/workspace/akri"
    ignore:
      paths:
        - "target"
        - ".github"

This configuration tells Mutagen to sync the current directory (your Akri code) to the specified path on your Raspberry Pi. It ignores the target directory and .github folder, which are not needed for development.

Also, make sure that the directory desired directroy, like /home/gaurav/workspace/akri, exists on your Raspberry Pi. You can create it using:

1
ssh akri-pi "mkdir -p /home/gaurav/workspace/akri"

Step 4: Start Mutagen Sync

Initialize the project with Mutagen:

1
mutagen project start

This command will start the synchronization process. Mutagen will analyze the directories and begin syncing files from your macOS machine to the Raspberry Pi.

You can check the status of the sync with:

1
mutagen sync list

If everything is set up correctly, you should see your Akri code being synced to the Raspberry Pi. Here’s an example output:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
Name: code
Identifier: sync_bNo8KQzBAmTwoBGrVZbyaaquMzNcGX8Mdgmq7NlOnEp
Alpha:
        URL: /Users/gaurav.gahlot/workspace/gauravgahlot/akri
        Connected: Yes
        Synchronizable contents:
                73 directories
                239 files (1.6 MB)
                0 symbolic links
Beta:
        URL: akri-pi:/home/gaurav/workspace/akri
        Connected: Yes
        Synchronizable contents:
                73 directories
                239 files (1.6 MB)
                0 symbolic links
Status: Watching for changes

Step 5: Build Akri on the Raspberry Pi (from macOS)

Now that your code is synced, you can build Akri directly on the Raspberry Pi without needing to SSH into it every time:

1
ssh akri-pi 'bash -l -c "cd /home/gaurav/workspace/akri && cargo build"'

If everything is set up correctly, you should see the build process start, and it will use the latest code synced from your macOS machine.


Troubleshooting

cargo Not Found When Using SSH?

If you face an error like:

1
bash: line 1: cargo: command not found

It means that the cargo command is not in the default PATH for non-interactive shells. To fix this, ensure that the Rust environment is set up correctly in your .bashrc or .bash_profile on the Raspberry Pi. You can add the following line to your .bashrc:

1
. "$HOME/.cargo/env"

target/ is still syncing?

If you notice that the target/ directory is still being synced, it might be because Mutagen has already started syncing it before you added it to the ignore rules.

Mutagen remembers previously synced files, so changing ignore rules won’t apply retroactively. To fully reset:

1
2
3
mutagen sync terminate akri-sync
mutagen project terminate akri-dev
mutagen sync flush

Then delete the residual directory on the Pi:

1
ssh akri-pi "rm -rf /home/gaurav/workspace/akri/target"

Now, restart the sync:

1
mutagen project start

Conclusion

Akri is a CNCF sandbox project aimed at enabling edge devices in Kubernetes. While it’s targeted at Linux-based environments, the developer ecosystem often includes macOS machines.

This setup allows you to develop Akri on macOS while leveraging the Raspberry Pi for building and testing. By using Mutagen, you can ensure that your code is always in sync with the Pi, enabling a smooth development workflow without needing to switch environments or worry about cross-compilation issues.

Feel free to reach out if you have any questions or run into issues while setting up your development environment. Happy hacking!