2023-01-19 16:42:32 +00:00
# Extension Install
2023-01-19 16:04:20 +00:00
2023-01-19 16:17:23 +00:00
Anyone can create an extension by following the [example extension ](https://github.com/lnbits/lnbits/tree/extension_install_02/lnbits/extensions/example ).
Extensions can be installed by an admin user after the **LNbits** instance has been started.
2023-01-19 16:42:32 +00:00
## Configure Repositories
2023-01-19 16:17:23 +00:00
Go to `Manage Server` > `Server` > `Extensions Manifests`
2023-01-20 08:47:47 +00:00
An `Extension Manifest` is a link to a `JSON` file which contains information about various extensions that can be installed (repository of extensions).
2023-01-20 08:03:56 +00:00
Multiple repositories can be configured. For more information check the [Manifest File ](https://github.com/lnbits/lnbits/blob/extension_install_02/docs/guide/extension-install.md#manifest-file ) section.
2023-01-19 16:17:23 +00:00
2023-01-20 08:03:56 +00:00
**LNbits** administrators should configure their instances to use repositories that they trust (like the [lnbits-extensions ](https://github.com/lnbits/lnbits-extensions/ ) one).
> **Warning**
2023-01-20 08:47:47 +00:00
> Extensions can have bugs or malicious code, be careful what you install!!
2023-01-19 16:42:32 +00:00
2023-01-20 08:21:19 +00:00
## Install New Extension
Only administrator users can install or upgrade extensions.
Go to `Manage Extensions` > `Add Remove Extensions`
A list of extensions that can be installed is displayed:
> **Note**
> If the extension is installed from a GitHub repo, then the GitHub star count will be shown.
Click the `Manage` button in order to install a particular release of the extension.
> **Note**
2023-01-20 08:47:47 +00:00
> An extension can be listed in more than one repository. The admin user must select which repository it wants to install from.
2023-01-20 08:38:38 +00:00
Select the version to be installed (usually the last one) and click `Install` . One can also check the `Release Notes` first.
> **Note**:
>
> For Github repository: the order of the releases is the one in the GitHub releases page
>
> For Explicit Release: the order of the releases is the one in the "extensions" object
2023-01-20 08:21:19 +00:00
2023-01-20 08:42:14 +00:00
The extension has been installed but it cannot be accessed yet. In order to activate the extension toggle it in the `Activated` state.
Go to `Manage Extensions` (as admin user or regular user). Search for the extension and enable it.
## Uninstall Extension
2023-01-20 08:47:47 +00:00
On the `Install` page click `Manage` for the extension you want to uninstall:
2023-01-20 08:42:14 +00:00
2023-01-20 08:47:47 +00:00
The installed release is highlighted in green.
Click the `Uninstall` button for the release or the one in the bottom.
Users will no longer be able to access the extension.
> **Note**
> The database for the extension is not removed. If the extension is re-installed later, the data will be accessible.
2023-01-20 08:42:14 +00:00
2023-01-19 16:42:32 +00:00
## Manifest File
The manifest file is just a `JSON` file that lists a collection of extensions that can be installed. This file is of the form:
```json
{
"extensions": [...]
"repos": [...]
}
```
There are two ways to specify installable extensions:
### Explicit Release
It goes under the `extensions` object and it is of the form:
```json
{
"id": "lnurlp",
"name": "LNURL Pay Links",
"version": 1,
"shortDescription": "Upgrade to version 111111111",
"icon": "receipt",
"details": "All charge names should be < code > 111111111< / code > . API panel must show: < br > ",
"archive": "https://github.com/lnbits/lnbits-extensions/raw/main/new/lnurlp/1/lnurlp.zip",
"hash": "a22d02de6bf306a7a504cd344e032cc6d48837a1d4aeb569a55a57507bf9a43a",
"htmlUrl": "https://github.com/lnbits/lnbits-extensions/tree/main/new/lnurlp/1",
"infoNotification": "This is a very old version"
}
```
2023-01-19 16:45:17 +00:00
< details > < summary > Fields Detailed Description< / summary >
2023-01-19 16:42:32 +00:00
| Field | Type | | Description |
|----------------------|---------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
2023-01-20 08:47:47 +00:00
| id | string | mandatory | The ID of the extension. Must be unique for each extension. It is also used as the path in the URL. |
2023-01-19 16:42:32 +00:00
| name | string | mandatory | User friendly name for the extension. It will be displayed on the installation page. |
| version | string | mandatory | Version of this release. [Semantic versoning ](https://semver.org/ ) is recommended. |
| shortDescription | string | optional | A few words about the extension. It will be displayed on the installation page. |
| icon | string | optional | quasar valid icon name |
| details | string (html) | optional | Details about this particular release |
| archive | string | mandatory | URL to the `zip` file that contains the extension source-code |
| hash | string | mandatory | The hash (`sha256`) of the `zip` file. The extension will not be installed if the hash is incorrect. |
| htmlUrl | string | optional | Link to the extension home page. |
| infoNotification | string | optional | Users that have this release installed will see a info message for their extension. For example if the extension support will be terminated soon. |
| criticalNotification | string | optional | Reserved for urgent notifications. The admin user will receive a message each time it visits the `Install` page. One example is if the extension has a critical bug. |
2023-01-19 16:45:17 +00:00
< / details >
2023-01-19 16:49:34 +00:00
This mode has the advantage of strictly specifying what releases of an extension can be installed.
2023-01-19 16:45:17 +00:00
2023-01-19 16:42:32 +00:00
### GitHub Repository
2023-01-19 16:49:34 +00:00
It goes under the `repos` object and it is of the form:
```json
{
"id": "withdraw",
"organisation": "lnbits",
"repository": "withdraw-extension"
}
```
2023-01-19 16:57:29 +00:00
| Field | Type | Description |
|--------------|--------|-------------------------------------------------------|
2023-01-20 08:47:47 +00:00
| id | string | The ID of the extension. Must be unique for each extension. It is also used as the path in the URL. |
2023-01-19 16:57:29 +00:00
| organisation | string | The GitHub organisation (eg: `lnbits` ) |
| repository | string | The GitHub repository name (eg: `withdraw-extension` ) |
2023-01-19 16:49:34 +00:00
2023-01-20 09:46:17 +00:00
The admin user will see all releases from the Github repository:
2023-01-19 16:57:29 +00:00
2023-01-20 09:46:17 +00:00
