Do you already have working app and now you would like to deploy it world wide to signage devices? By using signageOS Tools you can do exactly that. Let us show you how it's done.
What will you need?
- signageOS Account
- created Organization in Box (create one here)
- Node.js >= 10.15.0
- a shell environment (like bash, zsh, powershell...)
- a source-code editor (like VSCode, Sublime, WebStorm...)
I'll be using
zsh in this tutorial.
To get your existing application up and running you'll need only these few following steps:
- Install signageOS CLI Tools.
- Upload you application.
- Build and deploy.
Our demo application
On the following picture you can see the demo application that I'll be using throughout this tutorial. It's a simple web application compiled by Webpack. But you can use tools and compilators you like.
Now let's get started with detailed description of each step where I'll show you how easy it is.
Install signageOS CLI Tools
Even if you already have signageOS CLI Tools installed on your system, please, check if the CLI Tools are up to date. For the following steps you'll need version
0.6.0 or newer.
By using the following command you will get the newest version of the CLI Tools on to your system.
npm install @signageos/cli@latest -g
Thanks to the awesome CLI Tools you don't have to change anything in your current application. But before you upload and build your application, there is a few things to have in mind.
- Ignore everything you don't want us to see or your app doesn't need to run.
- Add signageOS to your application
- Test the application with our CLI Emulator, so you can build and deploy without worries.
- Login into the CLI Tools.
- Set default organization for the CLI Tools.
- Upload runnable code
Ignore unneeded files
If you are already using
.npmignore you are already set. But in case you want to ignore more or different files you can use
.sosignore. It works exactly the same as the previously mentioned ignore files.
To use features we offer you need to add signageOS dependencies to project. The first dependency
@signageos/front-display is mandatory to continue this tutorial. The second dependency
@signageos/front-applet is recommended to install especially if you are gonna use signageOS in your application.
# Mandatory npm i -SE @signageos/front-display # Highly Recommended and Mandatory for using signageOS JS APIs npm i -SE @signageos/front-applet
Test the application
Before you upload the application to signageOS and build it. It's a good practice to try if it's working in our CLI emulator tool. This will ensure less troubles debugging already built and deployed application.
cd my-awesome-application npx webpack # Or your build command sos applet start --applet-dir dist --entry-file-path dist/index.html
sos applet start \ --project-dir /Users/name/my-awesome-application \ --applet-dir /Users/name/my-awesome-application/dist \ --entry-file-path /Users/name/my-awesome-application/dist/index.html \ /
Login into the CLI Tools
Before you start with uploading your tested application you need to login using you Box account in to the CLI Tools.
Set default organization for the CLI Tools
sos organization set-default
Upload the application to signageOS
Your application is tested working, you are logged in and the organization is set. Let's upload.
cd my-awesome-application sos applet upload --entry-file-path dist/index.html
Build and deploy
After the upload finish. Follow the link provided by the CLI Tool and choose platform you want to deploy to. Click
Build and wait for the download link to appear.
What is the difference between npm start and sos applet start?
npm start will run our prepared compilation pipeline and emulator with hot reloaded enabled. This works only for projects generated by our CLI Tool.
sos applet start will only run the emulator without hot reload and compilation. It just runs your application. It works with projects generated by our CLI Tools. But it's main purpose is to run already existing application that use different technologies and project structure.
Error while uploading applet to signageOS via
sos applet upload?
The error might be caused by some of these situations:
If you do not have the
.sosignore file in your project, the
.gitignore is used instead. A solution to that is to add
.sosignore and put there all files and folders that are not supposted to be in the final built application. Usually the only thing you do not ignore is the
Make sure you definitely ignore the
Right now, there is a bug that prevents you to use
sos applet upload if your files or files in folders are completely empty. Please, check your project (usually the
/dist) folder for any empty files e.g.:
sos is undefined and cannot use the JS API
In case you do not have
sos object available, you need to manually add it to your project by one of the following options:
import sos from '@signageos/front-applet';
const sos = require('@signageos/front-applet');
<script src="..path/to/the/front-applet.js" />
You can manually download the library here: https://2.signageos.io/lib/front-applet/4.0.0/bundle.js. You can also download any other version by changing the
4.0.0. to other version that is available.
Unable to request PERSISTENT file system error in emulator console
If you encounter this error while running emulator in your browser, please make sure Chromium version is under 104. This version introduced breaking changes that prevent the communication of our front-display and front-applet through iframe. A fix is being worked on.