extern/netbox-docker
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox-docker.git synced 2025-06-08 11:06:39 +02:00
Code Issues Packages Projects Releases Wiki Activity

Rewrite Document for Clarity

Luke Anderson 2023-06-28 12:07:33 +09:30
parent e8f3171216
commit 2e53614de1
1 changed files with 28 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
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.