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

OR

• 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

OR

• 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:

• Netlify
• GitHub Pages
• GitLab Pages
• Static Site hosted in AWS S3 frontend by CloudFront
• Microsoft Azure Static Website hosting
• CloudFlare Pages
• Self-hosted Nginx Webserver
• Self-hosted Apache Web Server

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.