From 2e53614de1f681c392e23c18b5fa4c2d92cdf670 Mon Sep 17 00:00:00 2001 From: Luke Anderson Date: Wed, 28 Jun 2023 12:07:33 +0930 Subject: [PATCH] Rewrite Document for Clarity --- Using-Netbox-Plugins.md | 72 ++++++++++++++++------------------------- 1 file changed, 28 insertions(+), 44 deletions(-) diff --git a/Using-Netbox-Plugins.md b/Using-Netbox-Plugins.md index 833b4bd..f008d21 100644 --- a/Using-Netbox-Plugins.md +++ b/Using-Netbox-Plugins.md @@ -1,39 +1,28 @@ -To utilize plugins that have been created by users within the [NetBox Community](https://github.com/netbox-community/netbox/wiki/Plugins) a custom image must be used. +To utilize plugins that have been created by users within the [NetBox Community](https://github.com/netbox-community/netbox/wiki/Plugins) a custom Docker image must be created. + +# Step 1 - Fresh Install Lets start with a fresh install of netbox-docker. -* `git clone -b release https://github.com/netbox-community/netbox-docker.git` -* Change `/env/netbox.env` to your required settings. -* Create a few files these are (`plugin_requirements.txt`, `Dockerfile-Plugins`, `docker-compose.override.yml`) +1. Clone this repository `git clone -b release https://github.com/netbox-community/netbox-docker.git` to a new folder +2. If required, **change** the `/env/netbox.env` file to your required settings. +3. In the **root of the new folder**, **create** the following files (leave them blank): `plugin_requirements.txt` `Dockerfile-Plugins` `docker-compose.override.yml` -## Python Requirements -The `plugin_requirements.txt` file needs to contain all the plugins that are required. +# Step 2 - Modify New Files +## `plugin_requirements.txt` +This file contains a list of the NetBox Plugins (as **PyPi Python Packages**) to be installed during the building of the Docker image. +For Example: ``` -netbox-secretstore +netbox-topology-views==3.6.0b2 +netbox-validity +netbox-acls ``` -> NOTE: These must be on PyPi to work. - -## NetBox Configuration - -To get plugins to work within NetBox you need to add some configuration to `configuration/configuration.py`. - -```python -PLUGINS = ["netbox_secretstore"] - -# PLUGINS_CONFIG = { -# "netbox_secretstore": { -# ADD YOUR SETTINGS HERE -# } -# } -``` -> NOTE: This can differ for every plugin. To learn more about this see the [NetBox documentation](https://netbox.readthedocs.io/en/stable/plugins/#enable-the-plugin). - -## Custom Docker File - -The new `Dockerfile-Plugins` will enable us to build a new image with the required plugins installed. +## `Dockerfile-Plugins` +This is the Dockerfile used to build the custom Image. +Put the following contents into that file. ```Dockerfile FROM netboxcommunity/netbox:latest @@ -44,25 +33,21 @@ RUN /opt/netbox/venv/bin/pip install --no-warn-script-location -r /plugin_requi COPY configuration/configuration.py /etc/netbox/config/configuration.py COPY configuration/plugins.py /etc/netbox/config/plugins.py RUN SECRET_KEY="dummydummydummydummydummydummydummydummydummydummy" /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py collectstatic --no-input - ``` +The `SECRET_KEY` does not need to be changed. -> NOTE: You can swap the image out to use any of the images that the Netbox-Docker community publishes to [Docker Hub](https://hub.docker.com/r/netboxcommunity/netbox/tags). - -## Docker Compose Override - -`docker-compose.override.yml`, as its name implies, can contain configuration overrides for existing services or entirely new services. +## `docker-compose.override.yml` +As its name implies, this file can contain configuration overrides for `docker-compose.yml` +The absolute most basic configuration that you need is as follows. This tells our NetBox Worker and NetBox Housekeeping services to use our new custom image, `Dockerfile-Plugins` ```yaml -version: '3.4' +version: '3.4' # This is NOT the version of NetBox! No need to adjust :) services: netbox: - ports: - - 8000:8080 + image: netbox:latest-plugins build: context: . dockerfile: Dockerfile-Plugins - image: netbox:latest-plugins netbox-worker: image: netbox:latest-plugins build: @@ -73,23 +58,22 @@ services: build: context: . dockerfile: Dockerfile-Plugins - ``` -This configuration will change the ports `netbox` will use. It will also select the build file created in previous steps and tell the `netbox-worker` service to now use the new image (`netbox:latest-plugins`) that has been created. - -## Build and Deploy -To build and deploy this in docker two commands are required. +# Step 3 - Build and Deploy! +Once you've prepared the new Docker Image, now it's time to build it. +Execute the following commands: ```bash docker-compose build --no-cache docker-compose up -d ``` -## Troubleshooting +With any luck, your new custom NetBox-Docker Image has been created and is now running, with the required plugins installed! + +# Troubleshooting ### Plugin does not load - The error is something like `django.core.exceptions.ImproperlyConfigured: Unable to import plugin nextbox-plugin: Module not found`. Note that the plugin name for pip can be different from the name used to load the plugin. I.e. `netbox-plugin` for pip and `netbox_plugin` (note the underscore) for the config file. \ No newline at end of file