How to Install Extensions

Updated 205 Days AgoPublic

Actions

This document will explain how to download and install a Phorge Extension.
The instructions for installing Arcanist extensions would be covered elsewhere.

What Can Extensions Do - A Warning

Phorge extensions are just extra code that runs in the Phorge server.

Extensions are extremely powerful, but they are also extremely useful: they allow all sorts of integrations with external tools, make new flows possible, and make UI changes to existing applications. Extensions can also offer completely new applications, that automatically integrate into everything else in Phorge, including other extensions.

Installing an Extension

The common way to distribute an extension is by git cloneing it from its source, and place that next to the phorge and arcanist directories:

.
├── arcanist
├── phorge
└── my-extension

Get the clone url from the extension's page - for example, git://example.com/my-extension, and just clone it:

git clone git://example.com/my-extension

Then, to have Phorge load the new extension, update the load-libraries entry in conf/local/local.json file.

• If this is the first extension you're installing, you can use the command line tool bin/config to create the key:

echo '["my-extension/src"]' | bin/config set load-libraries --stdin

• For all other extensions, you'd like to manually edit the file in a text editor; The command above will delete whatever other extensions you might have installed.

The load-libraries entry is a list of paths; The path can be either relative to the parent directory of Phorge, or an absolute path. The path will normally end with src/, and needs to point at the directory containing the __phutil_library_init__.php file.

After Installing

After installing the extension, you should follow the Upgrading Phorge manual. You don't have to actually upgrade phorge and arcanist code, though now might be a good chance to do it.

Specifically, and depending on the extension, you should:

• stop the server and daemons
• run bin/storage upgrade (to configure the database for the extension)
• restart the server and daemons (to load the new code)

Upgrading

The flow for upgrading an extension is the same for upgrading Phorge - get the new code (normally using git pull), run bin/storage upgrade, and restart.

Removing an Extension

To remove an extension, remove its entry from load-libraries in the conf.local file, and restart Phorge. You can then delete its code directory.
This will prevent it from being loaded, but will not remove any changes made in the database - those will be left to allow you to manually extract anything useful. You can use any common database management tool to clean them up afterwards.

Extensions might add data into common databases - things like "transaction kinds" and "edges" and Remarkup rules - that will not be readable after removing the extension. These might show up as "unknown object" in various UI setups, and might show up in logs as errors. In theory, these things should never cause any functionality to actually break, but bugs happen. Reach out for support if you run into an issue.