Skip to main content

How to: Package your App

This guide explains how to package your App to be distributed over the SyftBox platform, which is essential when deploying computations to run on varying remote machines that are part of the network. This assumes you're comfortable with shell scripting, virtual environments, and dependency management - but if you don't, this guide should get you going!

There are two main parts of one's App, especially when running on SyftBox:

  1. Packaging Script (e.g., run.sh): Sets up the runtime environment, manages dependencies, and launches your App.

  2. Application Code: Contains the core logic of your computation (e.g., main.py).

note

SyftBox executes this script within all locally installed Apps every 10 seconds, so the computations' results stay fresh. This frequency can be changed following the guide on running your Apps.

Overview​

The packaging script serves to:

  • Prepare the Environment: Create and activate a virtual environment (or equivalent) if one doesn't exist.
  • Install Dependencies: Ensure all required packages are installed.
  • Execute Your Application: Run your computation within the prepared environment.
  • Clean Up: Deactivate the environment once execution is complete.

Although our examples use Python, the approach is fully flexible—you may choose any runtime and packaging method that best suits your App:

#!/bin/sh
set -e

# Create a virtual environment, if it doesn't exist.
if [ ! -d .venv ]; then
  uv venv
fi

# Activate the virtual environment.
. .venv/bin/activate

# Install or upgrade dependencies.
uv pip install --upgrade -r requirements.txt

# Log execution details and run the App.
echo "Running 'my_app' with $(python3 --version) at '$(which python3)'"
python3 main.py

# Deactivate the virtual environment.
deactivate

Script guide step-by-step​

0. Prerequisites​

  • Familiarity with shell scripting and command-line operations.
  • A working Python environment (or equivalent for your chosen runtime).
  • SyftBox configured, so you can test your packaging script (run.sh).

1. Create the packaging script​

Create a file named run.sh in your project directory with the appropriate content. This should be at the root path of your project, so that SyftBox can find it and execute.

Additionally, you can create a dummy python file to be executed by the packaging script, i.e. main.py.

2. Create virtual environment​

The part of the script checks if a virtual environment exists and creates one if it doesn't, to avoid redundant venv setup.

We recommend using uv for managing environments.

if [ ! -d .venv ]; then
  uv venv
fi

. .venv/bin/activate

3. Install dependencies​

This is entirely up to you - but you can start with a requirements.txt file to list all the dependencies your App needs. The goal here is to install any needed 3rd party libs used by your code.

uv pip install --upgrade -r requirements.txt

A good practice is to keep your dependencies up-to-date, so you can add the --upgrade flag to the pip install command. Additionally, specifying specifc versions of the dependencies can help in ensuring reproducibility of your code.

4. Validate locally​

Before sharing your App to other users on SyftBox, it would be very useful to verify that:

  • The packaging script correctly creates and activates the virtual environment.
  • Your App code executes as expected.

Testing can be done as easy as running the run.sh on your local machine.

Ensure that you are not having a virtual environment activated when running the script, as it will create a nested virtual environment, which might create issues during your debugging.

5. Deploy and monitor on SyftBox​

Deploying your App to SyftBox is as easy as copying the files to the appropriate directory or cloning it directly from your repository - so you are ready to ask your friends to test it out.

Note that SyftBox will execute the run.sh script every 10 seconds, so you can monitor the logs to ensure that your App is running as expected. However, you cannot inspect the logs of other users of your App - so you might want to add some logging to your App or script to help with debugging.

Using a different runtimes than Python​

While this guide uses a Python example, the principles apply equally to other runtimes. For example:

  • Node.js:
    • Setup: Use npm or yarn to install dependencies listed in package.json.
    • Execution: Run your App with commands like node main.js.
  • Java:
    • Setup: Use Maven or Gradle to manage dependencies and build your App.
    • Execution: Package your App as a JAR file and run it using java -jar yourapp.jar.
  • Go:
    • Setup: Utilize Go modules to manage dependencies.
    • Execution: Build your App into a binary and run the executable directly.

The key considerations stay the same:

  • Environment management: Adapt the concept of a virtual environment to your chosen language's best practices (e.g., using containers or isolated build environments).
  • Dependency handling: Ensure all dependencies are declared in the appropriate manifest files.
  • Execution Commands: Replace Python-specific commands with those relevant to your runtime environment.

Conclusion​

This guide provides a starting point for packaging your App for SyftBox, which is a critical step in ensuring reproducibility and reliability when running computations on remote machines.

You are ready now to package your App for SyftBox and share it with your collaborators on the network!