Deploy on the gateway
Transfer the files to the gateway
Push with scp
You can deploy your files using scp
from your host:
scp my-binary admin@lorix-one-xxxxxx.local:/home/admin
You can also browse your gateway file system and transfer data with a SCP client like Filezilla (scp mode) or WinSCP.
Pull with wget
You can host your binary and configuration files on a web server and get it from the gateway:
wget http://your.host.com/my-binary
Where to store the files
As an integrator, you will generally add software that is optional to the system. Your software may be composed of binaries and configuration/resources. We recommend using the following locations to store those files to avoid any collision with other current and future files of the system:
File type | Location | Example files |
---|---|---|
Binary | /opt | /opt/my-app/my-app |
Libraries | /opt | /opt/my-app/external-library.so |
Configuration | /etc/opt | /etc/opt/my-app/my-app.conf |
Resources | /etc/opt | /etc/opt/my-app/remote-server.cer |
Run the application at startup
In production, the gateway will rarely be restarted. But when it will, you'll most likely be happy if your program is launched automatically at startup.
Launching application at startup is the responsibility of the init system. LORIX OS uses OpenRC as init system.
You can read the OpenRC user guide to get an introduction of the init system and understand how it will help.
You can also find more details regarding OpenRC general usage in LORIX OS in the services management page.
To configure your application for boot at startup, you have to:
- Explain to OpenRC how you application works by creating an OpenRC service script
- Configure when to start it by registering the service in a runlevel
This simply consists in creating a file and a symbolic link.
Creating a service script
The content of the service script will depend on how your application works. If it respects some standards, the script can be very easy.
You can find all the details on how to make your service script on the official documentation: OpenRC Service Script Writing Guide (see the embedded version).
The documentation is quite impressive as it explains how to handle a lot of scenarios. Most application will probably only need a service file with a few lines.
The services scripts are stored in /etc/openrc.d/
: e.g. /etc/openrc.d/my-app
.
Prefix all your services with your own prefix so that you ensure it will never collide with new files that may be installed during updates.
If the service dies unexpectedly, you can supervise it with OpenRC and the supervise-daemon so that it will be automatically restarted.
You can get more information about the Supervise daemon guide.
Add the service to a runlevel
Adding the service will make it start automatically on the next boot. Depending the dependencies configured, it may prevent remote connection to the gateway. Be sure to test your service scripts on accessible devices before running them in production.
Once the service script is available, you can register the service to a runlevel. The available runlevels in LORIX OS are:
- no (nonetwork)
- boot
- sysinit
- default
- shutdown
The services of these runlevels are started in the above order (except no, which is never called on LORIX OS). You can register your service in any runlevel, but most of the time you may want to start it when the system is up, in the default
runlevel.
You can see the services of each runlevel with:
rc-status -a
To add your service to a runlevel run:
sudo rc-update add <service> <runlevel>
Example: add the 'my-app' service to the 'default' runlevel
sudo rc-update add my-app default
From now, your service will be started on the next boot!
If you want to start the service now, run:
Example: start the 'my-app' service
sudo rc-service my-app start
Each runlevel is represented by a directory in /etc/runlevels. These directories contains symbolic links to the service script that are enabled for the runlevel.