Netbox Docker Plugin
Manage Docker with Netbox & style. Made to work with netbox-docker-agent.
Thanks dzove855 for the presentation of the plugin the 15th April 2025 during the Netbox Community Call.
How does it work?
sequenceDiagram
Netbox->>Agent: Change (Webhook)
Agent->>Docker API: Request (HTTP)
Docker API->>Agent: Response (HTTP)
Agent->>Netbox: Feedback (Callback)
Once the plugin and webhooks are installed, you can:
- Create hosts that point to agents you had installed *
- Retrieve informations from Docker API with the help of the agent
- Create containers on host with an image, expose ports, add env variables and labels, mount volumes, set networks.
- Manage the container status, start, stop, restart.
- adding a host with curl needs a specific Origin header to make it working. Example :
curl -X POST -H "Authorization: Token xxxxx" -H "Content-Type: application/json" -H "Origin: https://myhost" https://myhost/api/plugins/docker/hosts/ -d '{"name": "test-add", "endpoint": "[https://xxxx:xxxx@test.com:1990"}](https://xxxx:xxxx@test.com:1990%22%7D)'
Installation
Below the compatibility list of the Netbox Docker PLugin and Netbox. Please chose the right version of the plugin depending of the Netbox version you use:
| Netbox Version | Netbox Docker Plugin Version |
|---|---|
| 3.* | 1.* |
| 4.0.* | 2.* |
| 4.1.* | 3.* |
You can follow the official plugins installation instructions.
If needed, source your Netbox's virtual environment and install the plugin like
a package. We assume you have already installed
Netbox and its source code are
in /opt/netbox:
cd /opt/netbox
python3 -m venv venv # if virtual env was not created before
source /opt/netbox/venv/bin/activate
pip install netbox-docker-plugin
Enable the plugin in the /opt/netbox/netbox/netbox/configuration.py file:
PLUGINS = [
'netbox_docker_plugin',
]
Then, run migrations:
cd /opt/netbox
python3 netbox/manage.py migrate
Alternative
Another way to install Netbox is to use the Official netbox-docker project.
With this alternate way, you can customize your Netbox image and migrations will be automatically execute each time you restart the container.
Contribute
Install our development environment
Requirements:
- Python 3.11
- PostgreSQL 15 Official Netbox doc
- user: netbox (with database creation right)
- password: secret
- database: netbox
- port: 5432
- Redis 7.2
- port: 6379
Set a PROJECT variable :
PROJECT="/project/netbox"
Create a project directory $PROJECT:
mkdir $PROJECT
Go inside your project directory, clone this repository and the Netbox repository:
cd $PROJECT
git clone git@github.com:SaaShup/netbox-docker-plugin.git
git clone git@github.com:netbox-community/netbox.git
Create your venv and activate it:
python -m venv venv
source venv/bin/activate
Install netbox-docker-plugin dependencies:
cd $PROJECT/netbox-docker-plugin
pip install -e .
Configure Netbox and install Netbox dependencies:
cd $PROJECT/netbox
cp $PROJECT/netbox-docker-plugin/netbox_configuration/configuration_dev.py $PROJECT/netbox/netbox/netbox/configuration.py
pip install -r requirements.txt
Run database migrations:
cd $PROJECT/netbox
python3 netbox/manage.py migrate
Create a Netbox super user:
cd $PROJECT/netbox
python3 netbox/manage.py createsuperuser
Start Netbox instance:
cd $PROJECT/netbox
python3 netbox/manage.py runserver 0.0.0.0:8000 --insecure
Visit http://localhost:8000/
Run tests
After installing your development environment, you can run the tests plugin (you don't need to start the Netbox instance):
cd $PROJECT/netbox
python3 -m pip install requests_mock
python3 netbox/manage.py test netbox_docker_plugin.tests --keepdb -v 2
With code coverage, install coverage.py and use it:
cd $PROJECT/netbox
python3 -m pip install coverage
Then run the test with coverage.py and print the report:
cd $PROJECT/netbox
coverage run --include='*/netbox_docker_plugin/*' netbox/manage.py test netbox_docker_plugin.tests --keepdb -v 2
coverage report -m
Hosting
Check https://saashup.com for more information.
1 maintainer
Metadata
1 maintainer
Release files for netbox-docker-plugin 3.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| netbox_docker_plugin-3.4.0.tar.gz | 52.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| netbox_docker_plugin-3.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 157.9 kB
Release files / netbox_docker_plugin-3.4.0.tar.gz
| Download URL | netbox_docker_plugin-3.4.0.tar.gz |
|---|---|
| Size | 52.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e8a78c92ae63a98ef67fc1e8d030756f50af625cc1e6bcaf0ac751fcee6d6869
|
|
BLAKE2b-256 checksum How to use checksums |
d9e17f69adc36609f412316259224123662d0c70d9365e5132fc89a76fbb2baf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / netbox_docker_plugin-3.4.0-py3-none-any.whl
| Download URL | netbox_docker_plugin-3.4.0-py3-none-any.whl |
|---|---|
| Size | 105.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
86f74f6af11813f271dbc46c9f7417f2d754f549683cda0b901807f7854df3e0
|
|
BLAKE2b-256 checksum How to use checksums |
3d60a560b2e111982d091846096200d84d66d5ae5cf08206c8531da19de1a521
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency log
