App Setup Using systemctl - FreeWaveTechnologies/ZumIQ GitHub Wiki

This procedure describes the basic steps needed to get an app installed and running in the ZumIQ environment using systemctl.

This ony works with firmware versions v1.3.1.1 and later. For earlier firmware versions, use runit instead of systemctl. See the wiki page App Setup Using runit.

• Hello World Example - Simple "Hello, World" examples in a variety of programming languages.
• Installing and Starting - Step-by-step procedure explaining how to get an app running.
• Installation Helper Script - Helper script that can automate parts of app installation and setup.
• Systemd Services Run as Root - Not as devuser. This may cause problems at first.
• Advanced App Control - More information on using systemd tools to manage services.

For the purpose of this procedure, we will use a simple Python 3 "Hello World" web app, built on the Flask web framework. following the procedure documented below.

The basic procedure is:

1. Install Prerequisites
2. Create App Directory
3. Copy App Files to Device
4. Create systemd Service

Login to the device as devuser (see Logging In).

First, ensure that the package index is up-to-date:

sudo apt update

(Optional) Upgrade any existing packages:

sudo apt upgrade

Python 3 is on the device by default. If pip3, the Python package manager, is not on the device, it will need needs to be manually installed:

sudo apt install python3-pip

Finally, use pip3 to install the Flask module:

sudo pip3 install flask

Change directory to /home/devuser/apps

cd ~/apps

Create an app directory.

mkdir HelloDemo
cd HelloDemo

App files must be manually copied to the device using one of the techniques described on the Transfer Files page.

NOTE: If you copy the files to the device using the PTP Drag-and-Drop or Website, you will need to move the files from the upload location in the /ptp directory to the app directory created above. Assuming the file is named hello.py:

cd /ptp
mv hello.py ~/apps/HelloDemo

NOTE: If you copy the files to the device using SCP, you have the option of copying the files directly into the app directory created above.

For simple examples such as this one, the files can be created and edited directly on the device in the app directory.

For the purpose of this example, we will assume that you have a file named hello.py located in /home/devuser/apps/HelloDemo, containing the following code.

from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello World!"

if __name__ == "__main__":
    app.run(host='0.0.0.0')

Create a Unit file to define a systemd service for your HelloDemo app. Call this file hellodemo.service. You can create the file in the /home/devuser/apps/HelloDemo directory:

[Unit]
Description=Hello world systemd service.

[Service]
Type=simple
ExecStart=/usr/bin/python3 /home/devuser/apps/HelloDemo/hello.py

[Install]
WantedBy=multi-user.target

This defines a simple service. The critical part is the ExecStart directive, which specifies the full pathnames for both the command (python3) that will run the app, and the app itself (hello.py).

Copy the Unit file to /etc/systemd/service and give it permissions:

sudo cp hellodemo.service /etc/systemd/system/.
sudo chmod 644 /etc/systemd/system/hellodemo.service

With the Unit file in the /etc/systemd/system directory, you are ready to test the service:

sudo systemctl start hellodemo.service

You can verify that the app is running by using ps:

ps -ef | grep hello

This will result in something like the following:

root       864     1 38 18:10 ?        00:00:05 /usr/bin/python3 /home/devuser/apps/HelloDemo/hello.py

You can also check its status using the systemctl status command:

sudo systemctl status hellodemo

Finally, to verify that the app is actually functioning as expected, in a web browser, go to <IP address>:5000. The website should respond with "Hello, World!":

The service can be stopped or restarted using standard systemd commands.

sudo systemctl stop hellodemo.service
sudo systemctl restart hellodemo.service

Finally, use the enable command to ensure that the service starts whenever the system boots:

sudo systemctl enable hellodemo.service

You can use the disable command to disable this autostart action:

sudo systemctl disable hellodemo.service

The helper script add-service.sh is included to help in getting an app running as a service. It's located in /home/devuser/bin which is in the path by default. It will create the /etc/systemd/system Unit file automatically, and enable and start the service.

To use, you first need to complete steps 1-3 in Installing and Starting above, to get the app files onto the device. Note that this script requires that you place your app in a subdirectory under /home/devuser/apps.

Usage:

add-service.sh <app folder name> <app startup command(s)>

For the example in Installing and Starting above, this looks like:

add-service.sh HelloDemo "/usr/bin/python3 /home/devuser/apps/HelloDemo/hello.py"

This will create the Unit file hellodemo.service in /etc/systemd/system.

NOTE: Using the add-service.sh script is entirely optional. It is provided as a starting point for understanding how to install and run apps as services, but it is not intended to represent the definitive procedure. Do whatever works best for your application.

It's important to remember that all systemd services run as root; that is, they run as if the root user were running the command. That's why it's important to include the full pathname for commands and executables, such as "/usr/bin/python3 /home/devuser/apps/HelloDemo/hello.py" in the ExecStart field when creating the Unit file, or as an argument when invoking the add-service.sh helper script.

If systemd is not running your app properly, check pathnames and permissions on all files and directories associated with your app. To troubleshoot it, change to a different directory and try executing the ExecStart command manually, as root. For example:

cd /
sudo /usr/bin/python3 /home/devuser/apps/HelloDemo/hello.py

For more information about the Unit file and its available configuration options, see the systemd documentation.

Much of the information on this page came from Use systemd to Start a Linux Service at Boot from Linode.