Skip to main content

BYOB (Bring Your Own Box)

Instead of obtaining a SamizdApp Box from us, you can install SamizdApp on a device of your choosing. Note: the device must be capable of running balenaOS. There may also be additional hardware requirements for running SamizdApp.

To setup your box, you'll need to connect it to balenaCloud. Balena is used for managing deployments of the SamizdApp software to your box. The recommended way to connect to balena is to join the official SamizdApp fleet. However, if you wish to customize the software on your box or contribute to the development of SamizdApp, you'll need to configure self-managed deployments.

Ensure your device is powered off before beginning.

The recommended way to setup your box is to join the official SamizdApp fleet.

  1. Open up the fleet at: https://hub.balena.io/organizations/gh_rynomad/fleets/alpha.

  2. Click on "Get started" to add your device to the fleet.

  3. Follow the instructions on the right of the "Add new device" screen (after inserting the SD card, plug in ethernet and power on the device):

    1. Once the device has powered down, remove the SD card from the device.

      For Rock Pi: balena's instructions specify that the device is powered off when the LED is no longer on. The blue LED indicates the device is on; the green LED indicates the device is merely plugged in, and so will not turn off.


    2. Power off and power back on the device (by disconnecting and reconnecting the power).

    3. Close the "Add new device" screen.

    4. If the device does not shutdown: This means that setup has not completed. Setup should not take more than a few minutes. Reattempt setup by turning the device off and back on. The most common cause of setup not completing is bad WiFi credentials.

  4. Wait for 10 minutes for the device to finish updating, then proceed to install the client.

Self-Managed Deployments (For Developers)​

If you wish to customize the software on your box or contribute to the development of SamizdApp, you'll need to manage deployments to your box yourself.

Add Device to Fleet​

To setup and configure your box using balena, you'll need to create a free balenaCloud account, create a fleet, and add your device to that fleet. This section assumes your device is a ROCK Pi 4B; however, any of the devices that balena supports should work.

  1. Sign up for an account at https://dashboard.balena-cloud.com/.

  2. From the "Fleets" screen, click "Create fleet".

  3. Follow the docs at https://www.balena.io/docs/learn/getting-started/raspberrypi3/nodejs/#create-a-fleet to finish creating your fleet, adding your device, and provisioning your device.

  4. Follow the remainder of the "Add new device" Instructions section (after inserting the SD card, power on the device):

    1. Once the device has powered down, remove the SD card from the device.

      For Rock Pi: balena's instructions specify that the device is powered off when the LED is no longer on. The blue LED indicates the device is on; the green LED indicates the device is merely plugged in, and so will not turn off.


    2. Power off and power back on the device (by disconnecting and reconnecting the power).

    3. Close the "Add new device" screen. You should see your device listed under the "Devices" tab, and you should see it's status change to "Online".

    4. If the device does not shutdown: This means that setup has not completed. Setup should not take more than a few minutes. Reattempt setup by turning the device off and back on. The most common cause of setup not completing is bad WiFi credentials.

  5. While you're device boots up, go to the "Variables" page (left-hand side navbar) for your fleet; click "Add variable", input the following info, and then click "Add":
    Service: "All services"
    Name: MDNS_TLD
    Value: samizdapp.local

  6. Now go back to the "Summary" page (left-hand side navbar again) for your fleet. Once your device shows up in your fleet dashboard with the status "Online", your device should be ready to go.

  7. Remember to remove the SD Card from your device once it is set up.

Clone the Repository​

Use Git to clone the Herakles repo into your dev environment:

git clone git@github.com:samizdapp/herakles.git --recurse-submodules

The remainder of the docs will assume that you are in the base directory of the Herakles repo unless otherwise specified:

cd herakles/

Configure Your Dev Environment​

In order to easily deploy code from your dev environment to your box, you'll need to install the balena CLI.

  1. Continue following the same docs as before to install balena CLI: https://www.balena.io/docs/learn/getting-started/raspberrypi3/nodejs/#install-the-balena-cli

Push a Release​

After the CLI is installed, and you have logged in, you can push a release of SamizdApp to your box.

  1. Build the entire project and push it to your device via balenaCloud (expect this to take awhile before completing):

    balena push ${org}/${fleet} -m

    where ${org} is the name of your organization, typically your username, and ${fleet} is the name you gave to you fleet. (The full slug of your fleet can easily be copied from the fleet Summary page.)

  2. Once the push has successfully completed, balena will propagate it to all the devices in your fleet. You can monitor this in the dashboard page for your device in balenaCloud. Once the release for all services has been updated, the deployment is complete. You can monitor the logs for any runtime errors.