@roadiehq/roadie-cli NPM

Roadie CLI

A command line tool to develop, build and deploy plugins compatible with Roadie.io.

Enables the possibility to rebuild and repackage standard Backstage plugins to be instantly deployable to Roadie instances.

Installation

Prerequisites: Node.js and NPM/Yarn installed.

You can install the command line tool globally as a node.js compatible package by using either NPM or Yarn.

npm install -g @roadiehq/roadie-cli

yarn global add @roadiehq/roadie-cli

Commands

plugin:build [options] Build a plugin
plugin:dev [options] Run a plugin on dev mode
roadie-entity:create [options] Create an entity in the roadie entity database
roadie-entity:list [options] List entities in the roadie entity database
roadie-entity:delete [options] Delete an entity from the roadie entity database
roadie-entity-set:load [options] Load entities from a file into the roadie entity database

Developing with Roadie CLI

Create a Backstage plugin either using the Backstage CLI or other means
Install Roadie CLI
Run Roadie CLI in development mode against the plugin you have created
- roadie plugin:dev --location ~/Development/my-roadie-plugins/my-custom-plugin-folder/ --output ~/Development/temp --port 7046 Available options:

Option	Name	Description	Example
--location -l	Location	(Required) The absolute path to the folder where your plugin resides	`-l $PWD/my-plugin` / `-l /home/myname/Development/roadie-plugins/my-plugin`
--port -p	Port	(Required) HTTP Port to use for the local server to serve files from.	`-p 8765`
--output -o	Output directory	The absolute path to the folder where you want to generate the Roadie compatible plugin code	`-o $PWD/my-plugin/dist` / `-o /home/myname/Development/roadie-plugins/my-plugin/dist`

Building a plugin for production

Create a Backstage plugin either using the Backstage CLI or other means
Install Roadie CLI
Run Roadie CLI build command against the plugin folder you have created
- roadie plugin:build --location ~/Development/my-roadie-plugins/my-custom-plugin-folder/ --host https://my-plugins.domain.com/myCustomPlugin

Run Roadie CLI build command against a published NPM package (Currently public packages in npmjs.org registry are supported):
- roadie plugin:build --package @roadiehq/backstage-plugin-prometheus --host https://my-plugins.domain.com/prometheusPlugin

Available options:

Option	Name	Description	Example
--location -l	Location	(One of location or package is required) The absolute path to the folder where your plugin resides	`-l $PWD/my-plugin` / `-l /home/myname/Development/roadie-plugins/my-plugin`
--package -p	Package	(One of location or package is required) NPM Package to use to build a Roadie Plugin	`-p @roadiehq/backstage-plugin-prometheus`
--host -h	Host	(Required) Fully qualified URL to the location where these files will be hosted. The Production URL	`-h https://my-plugins.domain.com/prometheusPlugin` / `-h https://calm-parfait-833e94.netlify.app`
--output -o	Output directory	The absolute path to the folder where you want to generate the Roadie compatible plugin code	`-o $PWD/my-plugin/dist` / `-o /home/myname/Development/roadie-plugins/my-plugin/dist`
--workdir -w	Working directory	Used for cases where package option is used. A directory to use to download, unpackage and build the wanted NPM package	`-w $PWD/my-plugin/temp` / `-w /home/myname/temp/downloads`
--withUpload -u	Enable AWS S3 upload mode	A flag to upload generated files to S3. Bucket info is defined in env variable S3_BUCKET_NAME & S3_BUCKET_PREFIX	`-u`

Deploying

The CLI creates bundled static assets containing JS and CSS files. These files can be deployed to any static asset hosting solutions as long as they support providing these assets via HTTPS protocol. Possible hosting solutions:

Deploying automatically to AWS S3

The CLI provides a build option flag --withUpload / -u to automatically upload the constructed static assets to an AWS S3 bucket. To configure the bucket and the path where the files should be uploaded configure the environment variables S3_BUCKET_NAME and S3_BUCKET_PREFIX to match the wanted values.

Security

There are multiple ways to secure static assets if needed. If you are hosting your code internally within your infrastructure the easiest approach to secure the files is to secure the Nginx/Apache webservers (or other solutions) behind a VPN connection. When hosting the files on a hosting provider it could be beneficial to use edge functions, if possible, to intercept and identify requests to static assets.

In most cases the plugin code itself is something that is not needed to be hosted in a secure environment. For more lightweight approach to security an obfuscation approach could be enough. This would happen if the produced assets would be hosted somewhere like https://mydomain.com/32f078b6-19a9-11ee-be56-0242ac120002 or similarly unguessable URL.

Regardless of the approach it is always best practice to not hardcode URLs, secrets or other sensitive information into the deployed plugin code, but to use Roadie proxies, broker and secrets instead to handle connections securely.

backstage roadie plugins