Install, Update and Publish Plugins

This page is for the admin who runs a Broadcast server, and for authors who want to know what that person sees. Only a user with sudo access can manage plugins.

Install a plugin

1. Go to Application > Plugins.
2. In Upload a plugin, choose a .broadcast-plugin file and click Upload.
3. Review the page that opens.
4. Click Deploy.
5. Turn the plugin on in each channel that needs it.

Nothing runs until you deploy it and turn it on in a channel.

What to review

The review page has four parts:

Where it came from. A plugin you upload shows Not from the plugin directory. Install it only if you trust where it came from.

Permissions. What the plugin may do, in plain words. Each one has a level:

What it adds. Its hooks and pages.

Code. The real code that will run, and the manifest. For an update, this shows the changes since the live version.

Turn it on in a channel

A plugin is installed once on the server and turned on for each channel. You can do this in two places:

• In the Channels column of Application > Plugins. It opens a list where you tick channels.
• On the channel’s plugin page. Open the plugin, find Channels, and click Open. In the sidebar, this page is Plugins > In this channel.

The channel page has a switch for each plugin. Settings and permissions holds the plugin’s settings and any elevated permissions.

Settings belong to one channel. A secret setting shows Saved (hidden) and is never shown again. Leave it empty to keep the saved value.

Who can see plugin pages

Plugin pages, panels and widgets show only for team members who hold every data permission that the plugin holds in that channel.

Update a plugin

To update a plugin you uploaded:

1. Upload the file with the new version.
2. Review the changes, then click Deploy.

The new code runs from the next call. The channels stay on, and the settings stay saved. Permissions are approved for each version, so review them each time.

A version number can be used once. You cannot upload an older version.

Roll back

If a new version has a problem, open the plugin and find Earlier versions. Click Roll back next to the version you want. It goes back to a version you approved before, with the permissions it had.

Turn off and remove

• To stop a plugin in one channel, use its switch.
• To remove it, open the plugin and click Remove. This deletes the plugin, all its versions, settings and stored data on this server. The audit log keeps a record.

When a plugin keeps failing

A plugin that fails 20 times in a row is turned off in every channel, and the admins get an email. The plugin page shows the last error. To turn it on again, deploy a version or roll back.

Safe mode

Safe mode stops every plugin at once. Everything else in Broadcast keeps working. Use it if a plugin causes trouble and you cannot reach the web page.

On a managed server, run this:

./broadcast.sh plugins safe-mode on

To go back, run ./broadcast.sh plugins safe-mode off. On a manual installation, set BROADCAST_PLUGINS_SAFE_MODE=1 in the server’s environment and restart. See CLI Reference.

Audit log

Application > Plugins > Audit log lists who uploaded, deployed, turned on, turned off, rolled back and removed each plugin, and who changed its settings.

Share your plugin

There is no public plugin directory yet, so there is nowhere to publish a plugin for everyone. To share a plugin today, give the .broadcast-plugin file to the person who runs the other server. They upload it and review it as on this page.

Keep these points in mind:

• Your plugin’s ID must start with local.. Any other ID needs a signature from the plugin directory, and a package without one is refused.
• The other admin sees the warning about the source. Tell them what the plugin does and why it needs each permission. A README.md in the package is a good place.
• Send updates as new files with a higher version.

If you build with an agent or a draft

A draft that is sent for review shows in Application > Plugins as Version x.y.z waits for your approval. Click Review and deploy. From there it is the same review. See Testing and Debugging Plugins.