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.

For Example:

netbox-topology-views==3.6.0b2
netbox-validity
netbox-acls

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 /
RUN /opt/netbox/venv/bin/pip install  --no-warn-script-location -r /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

The SECRET_KEY does not need to be changed.

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
    ports:
      - 8000:8080
    build:
      context: .
      dockerfile: Dockerfile-Plugins
  netbox-worker:
    image: netbox:latest-plugins
    build:
      context: .
      dockerfile: Dockerfile-Plugins
  netbox-housekeeping:
    image: netbox:latest-plugins
    build:
      context: .
      dockerfile: Dockerfile-Plugins

Step 3 - 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

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.