How to use signageOS with existing application

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
• NPM
• a shell environment (like bash, zsh, powershell...)
• a source-code editor (like VSCode, Sublime, WebStorm...)

I'll be using VSCode and zsh in this tutorial.

To get your existing application up and running you'll need only these few following steps:

1. Install signageOS CLI Tools.
2. Upload you application.
3. 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.

1. Ignore everything you don't want us to see or your app doesn't need to run.
2. Add signageOS to your application
3. Test the application with our CLI Emulator, so you can build and deploy without worries.
4. Login into the CLI Tools.
5. Set default organization for the CLI Tools.
6. Upload runnable code

Ignore unneeded files

If you are already using .gitignore or .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.

node_modules/
my_secret_file.md

 

Add signageOS

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.

sos login

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.

More information

• Setup Developer Environment
• Build and Deploy your Applet

FAQ

What is the difference between npm start and sos applet start?

The npm start will run our prepared compilation pipeline and emulator with hot reloaded enabled. This works only for projects generated by our CLI Tool.

The 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.

Troubleshooting

Error while uploading applet to signageOS via sos applet upload?

The error might be caused by some of these situations:

Missing .sosignore
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 /dist folder.

Make sure you definitely ignore the .git folder!

Empty files
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.: .gitignore, .nojekyll, etc.

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:

Option A)

import sos from '@signageos/front-applet';

Option B)

const sos = require('@signageos/front-applet');

Option C)

<script src="..path/to/the/front-applet.js" />