Using Netbox Plugins

To utilize plugins that have been created by users within the NetBox Community a custom Docker image must be created.

Step 1 - Fresh Install

Lets start with a fresh install of netbox-docker.

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

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.

Add netbox-secrets If you are using Netbox > 3.5:

netbox-secrets

or add netbox-secretstore If you are using Netbox < 3.5:

netbox-secretstore

Dockerfile-Plugins

This is the Dockerfile used to build the custom Image.

Put the following contents into that file.

FROM netboxcommunity/netbox:latest

COPY ./plugin_requirements.txt /opt/netbox/
RUN /opt/netbox/venv/bin/pip install  --no-warn-script-location -r /opt/netbox/plugin_requirements.txt

# These lines are only required if your plugin has its own static files.
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

NOTE: This SECRET_KEY is only used during the installation. There's no need to change it.

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

version: '3.4' # This is NOT the version of NetBox! No need to adjust :)
services:
  netbox:
    image: netbox:latest-plugins
    pull_policy: never
    ports:
      - 8000:8080
    build:
      context: .
      dockerfile: Dockerfile-Plugins
  netbox-worker:
    image: netbox:latest-plugins
    pull_policy: never
  netbox-housekeeping:
    image: netbox:latest-plugins
    pull_policy: never

Step 3 - Enable plugins in the configuration

To get plugins to work within NetBox you need to add some configuration to configuration/plugins.py.

For Netbox > 3.5:

PLUGINS = ["netbox_secrets"]

# PLUGINS_CONFIG = {
#   "netbox_secretstore": {
#     ADD YOUR SETTINGS HERE
#   }
# }

or for Netbox < 3.5:

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.

Step 4 - Build and Deploy!

Once you've prepared the new Docker Image, now it's time to build it.

Execute the following commands:

docker compose build --no-cache
docker compose up -d

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.