Skip to content

Commit

Permalink
Closes #10696: Break out instructions for installing & rmeoving plugins
Browse files Browse the repository at this point in the history
  • Loading branch information
jeremystretch committed Apr 17, 2024
1 parent b8cedfc commit 70f2509
Show file tree
Hide file tree
Showing 4 changed files with 139 additions and 120 deletions.
121 changes: 2 additions & 119 deletions docs/plugins/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Plugins are packaged [Django](https://docs.djangoproject.com/) apps that can be installed alongside NetBox to provide custom functionality not present in the core application. Plugins can introduce their own models and views, but cannot interfere with existing components. A NetBox user may opt to install plugins provided by the community or build his or her own.

Please see the documented instructions for [installing a plugin](./installation.md) to get started.

## Capabilities

The NetBox plugin architecture allows for the following:
Expand All @@ -23,122 +25,3 @@ Either by policy or by technical limitation, the interaction of plugins with Net
* **Override core templates.** Plugins can inject additional content where supported, but may not manipulate or remove core content.
* **Modify core settings.** A configuration registry is provided for plugins, however they cannot alter or delete the core configuration.
* **Disable core components.** Plugins are not permitted to disable or hide core NetBox components.

## Installing Plugins

The instructions below detail the process for installing and enabling a NetBox plugin.

### Install Package

Download and install the plugin package per its installation instructions. Plugins published via PyPI are typically installed using pip. Be sure to install the plugin within NetBox's virtual environment.

```no-highlight
$ source /opt/netbox/venv/bin/activate
(venv) $ pip install <package>
```

Alternatively, you may wish to install the plugin manually by running `python setup.py install`. If you are developing a plugin and want to install it only temporarily, run `python setup.py develop` instead.

### Enable the Plugin

In `configuration.py`, add the plugin's name to the `PLUGINS` list:

```python
PLUGINS = [
'plugin_name',
]
```

### Configure Plugin

If the plugin requires any configuration, define it in `configuration.py` under the `PLUGINS_CONFIG` parameter. The available configuration parameters should be detailed in the plugin's README file.

```no-highlight
PLUGINS_CONFIG = {
'plugin_name': {
'foo': 'bar',
'buzz': 'bazz'
}
}
```

### Run Database Migrations

If the plugin introduces new database models, run the provided schema migrations:

```no-highlight
(venv) $ cd /opt/netbox/netbox/
(venv) $ python3 manage.py migrate
```

### Collect Static Files

Plugins may package static files to be served directly by the HTTP front end. Ensure that these are copied to the static root directory with the `collectstatic` management command:

```no-highlight
(venv) $ cd /opt/netbox/netbox/
(venv) $ python3 manage.py collectstatic
```

### Restart WSGI Service

Restart the WSGI service and RQ workers to load the new plugin:

```no-highlight
# sudo systemctl restart netbox netbox-rq
```

## Removing Plugins

Follow these steps to completely remove a plugin.

### Update Configuration

Remove the plugin from the `PLUGINS` list in `configuration.py`. Also remove any relevant configuration parameters from `PLUGINS_CONFIG`.

### Remove the Python Package

Use `pip` to remove the installed plugin:

```no-highlight
$ source /opt/netbox/venv/bin/activate
(venv) $ pip uninstall <package>
```

### Restart WSGI Service

Restart the WSGI service:

```no-highlight
# sudo systemctl restart netbox
```

### Drop Database Tables

!!! note
This step is necessary only for plugin which have created one or more database tables (generally through the introduction of new models). Check your plugin's documentation if unsure.

Enter the PostgreSQL database shell to determine if the plugin has created any SQL tables. Substitute `pluginname` in the example below for the name of the plugin being removed. (You can also run the `\dt` command without a pattern to list _all_ tables.)

```no-highlight
netbox=> \dt pluginname_*
List of relations
List of relations
Schema | Name | Type | Owner
--------+----------------+-------+--------
public | pluginname_foo | table | netbox
public | pluginname_bar | table | netbox
(2 rows)
```

!!! warning
Exercise extreme caution when removing tables. Users are strongly encouraged to perform a backup of their database immediately before taking these actions.

Drop each of the listed tables to remove it from the database:

```no-highlight
netbox=> DROP TABLE pluginname_foo;
DROP TABLE
netbox=> DROP TABLE pluginname_bar;
DROP TABLE
```
68 changes: 68 additions & 0 deletions docs/plugins/installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Installing a Plugin

!!! warning
The instructions below detail the general process for installing and configuring a NetBox plugin. However, each plugin is different and may require additional tasks or modifications to the steps below. Always consult the documentation for a specific plugin **before** attempting to install it.

## Install the Python Package

Download and install the plugin's Python package per its installation instructions. Plugins published via PyPI are typically installed using the [`pip`](https://packaging.python.org/en/latest/tutorials/installing-packages/) command line utility. Be sure to install the plugin within NetBox's virtual environment.

```no-highlight
$ source /opt/netbox/venv/bin/activate
(venv) $ pip install <package>
```

Alternatively, you may wish to install the plugin manually by running `python setup.py install`. If you are developing a plugin and want to install it only temporarily, run `python setup.py develop` instead.

## Enable the Plugin

In `configuration.py`, add the plugin's name to the `PLUGINS` list:

```python
PLUGINS = [
# ...
'plugin_name',
]
```

## Configure the Plugin

If the plugin requires any configuration, define it in `configuration.py` under the `PLUGINS_CONFIG` parameter. The available configuration parameters should be detailed in the plugin's `README` file or other documentation.

```no-highlight
PLUGINS_CONFIG = {
'plugin_name': {
'foo': 'bar',
'buzz': 'bazz'
}
}
```

## Run Database Migrations

If the plugin introduces new database models, run the provided schema migrations:

```no-highlight
(venv) $ cd /opt/netbox/netbox/
(venv) $ python3 manage.py migrate
```

!!! tip
It's okay to run the `migrate` management command even if the plugin does not include any migration files.

## Collect Static Files

Plugins may package static resources like images or scripts to be served directly by the HTTP front end. Ensure that these are copied to the static root directory with the `collectstatic` management command:

```no-highlight
(venv) $ cd /opt/netbox/netbox/
(venv) $ python3 manage.py collectstatic
```

### Restart WSGI Service

Finally, restart the WSGI service and RQ workers to load the new plugin:

```no-highlight
# sudo systemctl restart netbox netbox-rq
```
66 changes: 66 additions & 0 deletions docs/plugins/removal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Removing a Plugin

!!! warning
The instructions below detail the general process for removing a NetBox plugin. However, each plugin is different and may require additional tasks or modifications to the steps below. Always consult the documentation for a specific plugin **before** attempting to remove it.

## Disable the Plugin

Disable the plugin by removing it from the `PLUGINS` list in `configuration.py`.

## Remove its Configuration

Delete hte plugin's entry (if any) in the `PLUGINS_CONFIG` dictionary in `configuration.py`.

!!! tip
If there's a chance you may reinstall the plugin, consider commenting out any configuration parameters instead of deleting them.

## Re-index Search Entries

Run the `reindex` management command to reindex the global search engine. This will remove any stale entries pertaining to objects provided by the plugin.

## Uninstall its Python Package

Use `pip` to remove the installed plugin:

```no-highlight
$ source /opt/netbox/venv/bin/activate
(venv) $ pip uninstall <package>
```

## Restart WSGI Service

Restart the WSGI service:

```no-highlight
# sudo systemctl restart netbox
```

## Drop Database Tables

!!! note
This step is necessary only for plugins which have created one or more database tables (generally through the introduction of new models). Check your plugin's documentation if unsure.

Enter the PostgreSQL database shell (`manage.py dbshell`) to determine if the plugin has created any SQL tables. Substitute `pluginname` in the example below for the name of the plugin being removed. (You can also run the `\dt` command without a pattern to list _all_ tables.)

```no-highlight
netbox=> \dt pluginname_*
List of relations
List of relations
Schema | Name | Type | Owner
--------+----------------+-------+--------
public | pluginname_foo | table | netbox
public | pluginname_bar | table | netbox
(2 rows)
```

!!! warning
Exercise extreme caution when removing tables. Users are strongly encouraged to perform a backup of their database immediately before taking these actions.

Drop each of the listed tables to remove it from the database:

```no-highlight
netbox=> DROP TABLE pluginname_foo;
DROP TABLE
netbox=> DROP TABLE pluginname_bar;
DROP TABLE
```
4 changes: 3 additions & 1 deletion mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,9 @@ nav:
- Synchronized Data: 'integrations/synchronized-data.md'
- Prometheus Metrics: 'integrations/prometheus-metrics.md'
- Plugins:
- Using Plugins: 'plugins/index.md'
- About Plugins: 'plugins/index.md'
- Installing a Plugin: 'plugins/installation.md'
- Removing a Plugin: 'plugins/removal.md'
- Developing Plugins:
- Getting Started: 'plugins/development/index.md'
- Models: 'plugins/development/models.md'
Expand Down

0 comments on commit 70f2509

Please sign in to comment.