extern/netbox-docker
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox-docker.git synced 2025-06-08 19:16:47 +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. Lets start with a fresh install of netbox-docker.
* `git clone -b release https://github.com/netbox-community/netbox-docker.git` 1. Clone this repository `git clone -b release https://github.com/netbox-community/netbox-docker.git` to a new folder
* Change `/env/netbox.env` to your required settings. 2. If required, **change** the `/env/netbox.env` file to your required settings.
* Create a few files these are (`plugin_requirements.txt`, `Dockerfile-Plugins`, `docker-compose.override.yml`) 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 # Step 2 - Modify New Files
The `plugin_requirements.txt` file needs to contain all the plugins that are required. ## `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. ## `Dockerfile-Plugins`
This is the Dockerfile used to build the custom Image.
## 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.
Put the following contents into that file.
```Dockerfile ```Dockerfile
FROM netboxcommunity/netbox:latest 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/configuration.py /etc/netbox/config/configuration.py
COPY configuration/plugins.py /etc/netbox/config/plugins.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 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.yml`
As its name implies, this file can contain configuration overrides for `docker-compose.yml`
## Docker Compose Override
`docker-compose.override.yml`, as its name implies, can contain configuration overrides for existing services or entirely new services.
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 ```yaml
version: '3.4' version: '3.4' # This is NOT the version of NetBox! No need to adjust :)
services: services:
netbox: netbox:
ports: image: netbox:latest-plugins
- 8000:8080
build: build:
context: . context: .
dockerfile: Dockerfile-Plugins dockerfile: Dockerfile-Plugins
image: netbox:latest-plugins
netbox-worker: netbox-worker:
image: netbox:latest-plugins image: netbox:latest-plugins
build: build:
@ -73,23 +58,22 @@ services:
build: build:
context: . context: .
dockerfile: Dockerfile-Plugins 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. # Step 3 - Build and Deploy!
Once you've prepared the new Docker Image, now it's time to build it.
## Build and Deploy
To build and deploy this in docker two commands are required.
Execute the following commands:
```bash ```bash
docker-compose build --no-cache docker-compose build --no-cache
docker-compose up -d 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 ### Plugin does not load
The error is something like `django.core.exceptions.ImproperlyConfigured: Unable to import plugin nextbox-plugin: Module not found`. 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. 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.