• Background Image

    Getting Started with Mimix Nebula

    April 27, 2020

April 27, 2020

Getting Started with Mimix Nebula

The Mimix Nebula system of software deployment simplifies the packaging and distribution of cross-platform applications built with NodeJS, HTML, and WebSockets.
                                                                                      — D


Announcing Nebula

Today, we’re making available an early version of our Nebula deployment system for cross-platform applications. Nebula is an open source product, available free under the Blue Oak License and ready for you to customize to deploy your own HTML-based desktop applications with WebSockets on Windows, Mac, and Linux.


Get the Download

There are four ways you can get the free Nebula software:

  1. Download the Windows installer.
  2. Download the Mac installer.
  3. Download the AppImage for Linux.
  4. Download the source zip or tar and build from instructions.

The Nebula installer contains everything you need to experiment with creating and modifying a Nebula app without any “building” steps. Simply use your favorite text editor to modify the HTML/JS files. Note: The current release is not digitally signed. Click “Yes” in the Windows installation dialog to allow an “Unknown Publisher” (The Mimix Company) to install the app.

See: Index to Source Files

You can move to building from source when you’re ready to design your own back-end server or use a different set of frameworks than we include.

Before You Begin

We recommend reading Nebula: Simple & Flexible Applications with MSL Data before working with the Nebula download. It provides the background information and jumping-off points to help you think about the new kinds of applications you can build with Nebula based on the tools and frameworks you already know.

Disclaimer of Warranty

The Nebula software is licensed to you without cost on an as-is basis and without any warranty, express or implied. This free license does not include access to tech support. Bug fixes and upgrades, when and if they become available under this license, are your responsibility to install or integrate.

Why Nebula?

HTML applications offer a wealth of frameworks and tools for generating cross-platform user interfaces. Each developer has his or her own favorite code editor, web UI framework, and hosting solution. Where all of these fail to deliver is in packaging an application so that it can fully benefit from its cross-platform nature on all three desktop operating systems: Mac, Windows, and Linux.

The Nebula solution brings together the foundational elements needed to build a modern web application with HTML that can be rapidly deployed to any user desktop — without requiring a developer account signup anywhere and without committing to any specific UI framework or backend.

Here are the components we’ve packaged for you to build with. All of them are also open source and you can plug-in other packages or tools you prefer:

  1. Built-in local NodeJS webserver.
  2. Built-in Chromium browser.
  3. Built-in WebSocket server and receiver.
  4. Built-in “Local World,” an easy-to-edit HTML home page.
  5. Built-in data-binding, routing, and commanding (AngularJS).
  6. Built-in Bootstrap UI components.
  7. Built-in Bskit UI components and themes.
  8. Built-in MDI icon sets.
  9. Built-in custom color names.
  10. Access to local (packaged) or remote web pages.
  11. Access to any NodeJS service via WebSocket.
  12. All packaged in an Electron-based, one-click desktop executable for Windows, Mac, or Linux!

About the Tech Stack

The actual tech stack for our Mimix product, built with Nebula. The AngularJS components in purple and the SBCL (Lisp) code in green were design decisions based on our product requirements. You can choose any HTML/JS frontend and any NodeJS backend to use with Nebula. The red and orange “middleware” components represent our business logic and these can also be replaced by any NodeJS-based code you need. Nebula provides the working stack and the wiring to use either local or remote HTTP/HTML and local and remote WebSockets as data transports.

The Nebula tech stack was designed to fulfill our requirement that our apps be able to run locally on any platform or be hosted in the cloud. We also wanted our app to have a simple way to communicate with a server or another instance of itself over a network, or within the same machine.

These goals were achieved by stacking the Electron packaging system with an AngularJS front end. We chose AngularJS because of our experience with the framework and the body of our existing code that could be used to scaffold the app’s interface. You can use Nebula with any framework of your choice by simply substituting the AngularJS index.html file (and its supporting dependencies which are installed with Nebula) with an index.html and the appropriate dependencies for the framework(s) you want to use.

Because all HTML/JS frameworks work in a server/browser environment and Nebula provides both the built-in web server and browser for all platforms, all HTML/JS frameworks will work with Nebula.

Nebula Data Communications

As well as traditional web or desktop models, Nebula apps can benefit from the asynchronous separation of data and interface provided by multiple and separate WebSocket wires within each app instance.

Being regular HTML/JS apps, Nebula applications can communiciate using any standard protocol or API supported by the Chromium browser. We’ve included special scaffolding for WebSocket applications, a simple text-based, always-on communciations channel we use to let our app talk to a local or remote server or to another instance of the app itself.

We chose WebSockets because the format is pure text without API restrictions. This means you can send messages over WebSockets which use any existing API syntax — or you can make up an entirely new one to fit your application. Since our applications speak the MSL language, we use this wire to communicate MSL between our viewers and servers, but you could use the wire for anything — even a group chat.

Using WebSockets as data wires, separate from the HTML/JS user interface itself, opens up Nebula applications to a new kind of communication and UI paradigm.

Desktop apps communicate with data sources using the same monolithic app that draws the UI. Web applications rely on a remote server to perform any backend communications and to provide a renderable interface.

Nebula apps are enabled for a third kind of architecture, shown in the diagram. In this design, UI elements are delivered via HTML/JS while data is delivered on separate WebSockets for each source. This allows hot-swapping an interface over data, or vice-versa.

Components & Data Binding

We’ve chosen to include the Bootstrap UI components because they cover most of the requirements of modern UI design. Our Nebula app also contains many examples of data binding where application values are shown inside UI buttons or other elements, or where the appearance or functions of UI buttons are changed based on program values or values received over the WebSocket wire.

Using our sample code, you can quickly build a non-trivial AngularJS application, or you can replace our AngularJS components with your own components from a different framework.

Routing & Commanding

Because routing (figuring out what page to display) and commanding (executing a function in response to a button or menu item) are two of the most tedious parts of application design, we’ve scaffolded these into Nebula for you to use as a starting point. By examining and modifying our code, you’ll be able to connect your app’s buttons and menus to the back-end functions they need. We’ve also provided examples of how to make UI elements send data over WebSockets and how to respond to incoming WebSocket messages and update the UI.

Things to Try

The Mimix Nebula app demonstrates the HTTP web services, WebSocket services, data binding, routing, commanding, UI components, custom color settings, and icon sets which are included with the download.

After downloading the Nebula app for your platform (Windows, Mac, or Linux), you can experiment with the built-in controls before modifying the app to suit your needs.

WebSocket Communications

Nebula installs a local WebSocket server which you can connect to using the Local Mimix button in the interface. The local Mimix service provides an echo of whatever you send it. You can also connect to two public WebSocket servers which also echo what you send.

Once connected, use the Send button to send text over the WebSocket. The examples show MSL text from our programming language, but you can modify these in the source code.

Websocket messages you send and receive are shown in the UI in the order in which they took place. The Clear button erases the input text box and the Auto checkbox does so automatically after each WebSocket message is sent.

We’ve provided the scaffolding to easily modify this code to use WebSockets from any set of servers. The interface updates automatically to show Connect buttons for all the servers you define.

In addition to a standard WebSocket wire, we’ve provided a separate admin wire on a different port which your application might find useful. In Mimix, this wire is used to send admin commands to the server which are separate from the data, and you might find a simliar use for an admin wire in your app. Admin wires are defined in the built-in scaffolding. We use them to  increase security by ensuring that user-facing applications simply don’t have the wiring to communicate with admin servers.

Commanding & Data Binding

Most of the buttons in the sample UI contain examples of data binding and commanding. The orange Connect buttons, for example, are labeled with the server names which are dynamically taken from the list of WebSocket servers you define in the source.

When a WebSocket server connects successfully, the Send button is automatically updated with the server name and the button color is changed. Connecting also updates the banner component which opens the page, changing it from “Not Connected” to the version number of the connected server. This is an example of an AngularJS service updating the bound values for a separate UI component, in this case the banner. The banner detects the changes in the bound values and updates automatically without explicitly being called.

When data is received, the scrolling list of received messages is updated in the UI. You can move between servers sending different messages and the code is smart enough to preserve the “always-on” connection if it already exists or to start a new one if it doesn’t, using the same UI button.

While these examples are trivial, your application can use the same commanding and data binding methods to communicate with any kind of server and update the UI appropriately.

Navigation & Routing

The Nebula app includes built-in features for navigation and routing. The menu displayed across the top right is made of easy-to-edit JSON. AngularJS pages are contained within views, each view being made up of directives or custom HTML components with code behind them in controllers. Straightforward file organization inside the app’s folders makes it easy to find and edit the views or directives you need to build your app.

Fonts, Icons, & Colors

Icons and colors are often frustrating to add or edit inside non-trivial apps. The Nebula sample app includes a custom color naming system, making it easy to design named colors and apply them to all of your UI elements. On the home page, for example, you can click a color name to apply that color to a large icon on the page. We’ve included a custom font and the MDI icon set, too, as jumping-off points for you to choose your own fonts and icons.

Global and Scoped Data

Finally, we’ve included examples of both globally and locally scoped data, often a point of confusion in AngularJS apps. The version information shown on the app home page, for example, is a global value passed to the directive which displays it. The WebSocket messages on the same page are lexically scoped and visible only to the component that displays them. You can use these examples to build similar components in your apps without digging through documentation for working examples.

Other Scaffolding in the App

The Nebula app contains other functions it inherited from another product of ours. These are not utilized or documented in this release. However, an inspection of the source code will reveal the following ready-made and working features which you can use in your own Nebula app:

  • JSON-based data from local files or Firebase
  • User and app configuration settings
  • Protected routes with Google authentication (no keys/ids in app)
  • Page-style CMS with named, routable pages and JSON contents.
  • Blog-style posts with named, routable posts and JSON contents.
  • Modular components for displaying products and profiles.

Note that this version of the Nebula app will show console logs and error messages and also displays broken links and missing page content. The content was removed from this open source version because it contains code that is the subject of a US patent application.

You can visit the Ungallery app from which Nebula was built to see these features working in a production alpha.


Index to Source Files

The Nebula installers create the following folder structure under the directory where you choose to install this product. These examples (installation directory: c:\Nebula) are for Windows but the same structure applies under the installation directory for all platforms.

Contains nebula.exe, the desktop executable. For diagnostics, Nebula can be run from your own browser. See the documentation to start the local web server and for more information about building your own Nebula app from source.

Contains index.html, the app home page.

Contains folders for the custom controllers, css, directives, images, json, services, and views which comprise the AngularJS app. The AngularJS functions used to build these components are documented here. Notice you do not need to download or install AngularJS in order to begin coding with the installed app.

Contains one folder for each framework used by the app.

Contains the back-end servers for the app. Currently compiled, these will be released in open source later. You can replace the streams module with your own back-end and rebuild the app. For testing, simply run your server in a separate process and change the ports in the app to test from a browser.

— D 4/27/2020