Skip to content

Latest commit

 

History

History
77 lines (47 loc) · 3.89 KB

README.md

File metadata and controls

77 lines (47 loc) · 3.89 KB

Plugin Template

This template is designed to integrate easily with the main app in development.

A plugin consists of a React frontend and a Docker backend. It has a GitHub action that automatically runs npm run build and creates a release from the dist folder.

The main production app has an option to download a plugin from GitHub in the plugin manager.

To get started with developing a plugin:

Option 1: Clone the main repository and make a folder/repository inside of the plugins folder. Push only that folder to GitHub.

Option 2: If it is easier for you, copy all the contents of the plugin-template folder into a completely separate repository. All of the usage steps should still work.

Usage

  1. Follow the instructions in the README to install the app in development mode.

  2. Open a terminal and cd into your plugin's folder. Then run npm install to install your plugin's dependencies.

  3. Start the main app in development mode: Run npm run dev in the main project folder.

  4. Start the plugin in development mode: Run npm run dev in your plugin's folder.

  5. In the main app, go to the first menu dropdown and open the plugin manager. Click the plus, and paste the URL of your plugin (something like http://localhost:5172) in the development plugin option.

package.json

The first lines of the package.json are important to identifying your plugin.

"name": "plugin-template",
"pluginName": "Plugin Template",
"icon": "./icon.svg",
"index": "./index.html",
"dockerCompose": "./compose.yml",
  • name is considered to be the plugin id
  • pluginName is the display name of the plugin
  • icon is the dist-relative path to the icon for the plugin
  • index is the dist-relative path to the index HTML file generated by the build
  • dockerCompose is an optional dist-relative path to a Docker Compose file to run the plugin backend.

Plugin Development

A plugin page (React website) is hosted by the main app and lives in an iframe, in a completely separate context from the main app.

Running npm run dev starts a development server for the React website and starts the included Docker container via Docker compose (see backend folder).

If you want to avoid reinventing the wheel (in this case the common components of the main app), then feel free to copy them over to your app. They should work immediately. If not, you may need to copy one of the context providers from the main app and wrap it around your App component in a similar way to the Root component of the main app.

The default styles from the app are already available to you in the styles.css file.

A possible future development is communication between the plugin and main app. For now, things like dragging files will not work since there is no communication with the iframe.

Some contexts and components that may be useful to you:

  • OptionsPanel
  • ProgressPanel
  • ServerContext
  • DragContext
  • AlertContext
  • VisualizePanel
  • VisualizeSlicing in SlicesPage

Remember, these contexts are not available to you through the app's iframe, you must copy the code from the main app and use your own implementation.

Docker

The default Dockerfile and Docker Compose YAML should be a good starting point.

It is recommended to read the sample main.py in backend. This goes over a basic FastAPI server, but more importantly, it demonstrates how to use the Docker Volume Server (custom to Ouroboros).

Since plugins need to access files from the host file system (plugin frontends usually sends absolute file paths in the host file system), the Docker Volume Server provides functionality to copy files to and from a Docker volume (shared between all plugins and the main server).

Each plugin has its own folder in the volume, and files can easily be copied to or from that folder. Additionally, when an operation is done, you can easily clear out the folder.