netbox-docker-plugin


Namenetbox-docker-plugin JSON
Version 1.6.1 PyPI version JSON
download
home_pageNone
SummaryManage Docker with Netbox & style.
upload_time2024-04-22 12:20:07
maintainerNone
docs_urlNone
authorNone
requires_python>=3.8
licenseNone
keywords netbox netbox-plugin docker
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # Netbox Docker Plugin

[![Testing Report](https://github.com/SaaShup/netbox-docker-plugin/actions/workflows/main_ci.yml/badge.svg)](https://github.com/SaaShup/netbox-docker-plugin/actions/workflows/main_ci.yml)

Manage Docker with Netbox & style. Made to work with [netbox-docker-agent](https://github.com/SaaShup/netbox-docker-agent).

![UI Container view with dependencies](/docs/assets/screenshot.png)

## How does it work?

```mermaid
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:

1. Create hosts that point to
   [agents](https://github.com/SaaShup/netbox-docker-agent) you had installed
2. Retrieve informations from Docker API with the help of the agent
3. Create containers on host with an image, expose ports, add env variables and
   labels, mount volumes, set networks.
4. Manage the container status, start, stop, restart.

## Installation

You can follow [the official plugins installation
instructions](https://docs.netbox.dev/en/stable/plugins/#installing-plugins).

If needed, source your Netbox's virtual environment and install the plugin like
a package. We assume [you have already installed
Netbox](https://docs.netbox.dev/en/stable/installation/) and its source code are
in `/opt/netbox`:

```bash
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:

```python
PLUGINS = [
    'netbox_docker_plugin',
]
```

Then, run migrations:

```bash
cd /opt/netbox
python3 netbox/manage.py migrate
```

> [!IMPORTANT]
> In order to the communication between your Netbox instance and [the Agent](https://github.com/SaaShup/netbox-docker-agent)
> works, the plugin will check if webhooks to agents are
> presents on each migration phase.
> If not, then the plugin will automatically install webhooks configuration in
> your Netbox instance.

### Alternative

Another way to install Netbox is to use the [Official netbox-docker
project](https://github.com/netbox-community/netbox-docker).

With this alternate way, you can [customize your Netbox image](https://github.com/netbox-community/netbox-docker/wiki/Using-Netbox-Plugins) 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](https://github.com/netbox-community/netbox/blob/master/docs/installation/1-postgresql.md)
  - 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`:

```bash
mkdir $PROJECT
```

Go inside your project directory, clone this repository and the Netbox repository:

```bash
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:

```bash
python -m venv venv
source venv/bin/activate
```

Install netbox-docker-plugin dependencies:

```bash
cd $PROJECT/netbox-docker-plugin
pip install -e .
```

Configure Netbox and install Netbox dependencies:

```bash
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:

```bash
cd $PROJECT/netbox
python3 netbox/manage.py migrate
```

Create a Netbox super user:

```bash
cd $PROJECT/netbox
python3 netbox/manage.py createsuperuser
```

Start Netbox instance:

```bash
cd $PROJECT/netbox
python3 netbox/manage.py runserver 0.0.0.0:8000 --insecure
```

Visit http://localhost:8000/

### Run tests

After installing you development environment, you can run the tests plugin (you don't need to start the Netbox instance):

```bash
cd $PROJECT/netbox
python3 netbox/manage.py test netbox_docker_plugin.tests --keepdb -v 2
```

With code coverage, install [coverage.py](https://coverage.readthedocs.io/en/7.3.2/) and use it:

```bash
cd $PROJECT/netbox
python3 -m pip install coverage
```

The run the test with coverage.py and print the report:

```bash
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.

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "netbox-docker-plugin",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "netbox, netbox-plugin, docker",
    "author": null,
    "author_email": "Vincent Simonin <vincent@saashup.com>",
    "download_url": "https://files.pythonhosted.org/packages/0f/13/420515970eb4bda3cbbf797ae84bb529278852b710bacc46eaf8c901d094/netbox_docker_plugin-1.6.1.tar.gz",
    "platform": null,
    "description": "# Netbox Docker Plugin\n\n[![Testing Report](https://github.com/SaaShup/netbox-docker-plugin/actions/workflows/main_ci.yml/badge.svg)](https://github.com/SaaShup/netbox-docker-plugin/actions/workflows/main_ci.yml)\n\nManage Docker with Netbox & style. Made to work with [netbox-docker-agent](https://github.com/SaaShup/netbox-docker-agent).\n\n![UI Container view with dependencies](/docs/assets/screenshot.png)\n\n## How does it work?\n\n```mermaid\nsequenceDiagram\n    Netbox->>Agent: Change (Webhook)\n    Agent->>Docker API: Request (HTTP)\n    Docker API->>Agent: Response (HTTP)\n    Agent->>Netbox: Feedback (Callback)\n```\n\nOnce the plugin and webhooks are installed, you can:\n\n1. Create hosts that point to\n   [agents](https://github.com/SaaShup/netbox-docker-agent) you had installed\n2. Retrieve informations from Docker API with the help of the agent\n3. Create containers on host with an image, expose ports, add env variables and\n   labels, mount volumes, set networks.\n4. Manage the container status, start, stop, restart.\n\n## Installation\n\nYou can follow [the official plugins installation\ninstructions](https://docs.netbox.dev/en/stable/plugins/#installing-plugins).\n\nIf needed, source your Netbox's virtual environment and install the plugin like\na package. We assume [you have already installed\nNetbox](https://docs.netbox.dev/en/stable/installation/) and its source code are\nin `/opt/netbox`:\n\n```bash\ncd /opt/netbox\npython3 -m venv venv # if virtual env was not created before\nsource /opt/netbox/venv/bin/activate\npip install netbox-docker-plugin\n```\n\nEnable the plugin in the `/opt/netbox/netbox/netbox/configuration.py` file:\n\n```python\nPLUGINS = [\n    'netbox_docker_plugin',\n]\n```\n\nThen, run migrations:\n\n```bash\ncd /opt/netbox\npython3 netbox/manage.py migrate\n```\n\n> [!IMPORTANT]\n> In order to the communication between your Netbox instance and [the Agent](https://github.com/SaaShup/netbox-docker-agent)\n> works, the plugin will check if webhooks to agents are\n> presents on each migration phase.\n> If not, then the plugin will automatically install webhooks configuration in\n> your Netbox instance.\n\n### Alternative\n\nAnother way to install Netbox is to use the [Official netbox-docker\nproject](https://github.com/netbox-community/netbox-docker).\n\nWith this alternate way, you can [customize your Netbox image](https://github.com/netbox-community/netbox-docker/wiki/Using-Netbox-Plugins) and migrations will be\nautomatically execute each time you restart the container.\n\n## Contribute\n\n### Install our development environment\n\nRequirements:\n* Python 3.11\n* PostgreSQL 15 [Official Netbox doc](https://github.com/netbox-community/netbox/blob/master/docs/installation/1-postgresql.md)\n  - user: netbox (with database creation right)\n  - password: secret\n  - database: netbox\n  - port: 5432\n* Redis 7.2\n  - port: 6379\n\nSet a PROJECT variable :\n\n```\nPROJECT=\"/project/netbox\"\n```\n\nCreate a project directory `$PROJECT`:\n\n```bash\nmkdir $PROJECT\n```\n\nGo inside your project directory, clone this repository and the Netbox repository:\n\n```bash\ncd $PROJECT\ngit clone git@github.com:SaaShup/netbox-docker-plugin.git\ngit clone git@github.com:netbox-community/netbox.git\n```\n\nCreate your venv and activate it:\n\n```bash\npython -m venv venv\nsource venv/bin/activate\n```\n\nInstall netbox-docker-plugin dependencies:\n\n```bash\ncd $PROJECT/netbox-docker-plugin\npip install -e .\n```\n\nConfigure Netbox and install Netbox dependencies:\n\n```bash\ncd $PROJECT/netbox\ncp $PROJECT/netbox-docker-plugin/netbox_configuration/configuration_dev.py $PROJECT/netbox/netbox/netbox/configuration.py\npip install -r requirements.txt\n```\n\nRun database migrations:\n\n```bash\ncd $PROJECT/netbox\npython3 netbox/manage.py migrate\n```\n\nCreate a Netbox super user:\n\n```bash\ncd $PROJECT/netbox\npython3 netbox/manage.py createsuperuser\n```\n\nStart Netbox instance:\n\n```bash\ncd $PROJECT/netbox\npython3 netbox/manage.py runserver 0.0.0.0:8000 --insecure\n```\n\nVisit http://localhost:8000/\n\n### Run tests\n\nAfter installing you development environment, you can run the tests plugin (you don't need to start the Netbox instance):\n\n```bash\ncd $PROJECT/netbox\npython3 netbox/manage.py test netbox_docker_plugin.tests --keepdb -v 2\n```\n\nWith code coverage, install [coverage.py](https://coverage.readthedocs.io/en/7.3.2/) and use it:\n\n```bash\ncd $PROJECT/netbox\npython3 -m pip install coverage\n```\n\nThe run the test with coverage.py and print the report:\n\n```bash\ncd $PROJECT/netbox\ncoverage run --include='*/netbox_docker_plugin/*' netbox/manage.py test netbox_docker_plugin.tests --keepdb -v 2\ncoverage report -m\n```\n\n# Hosting\n\nCheck https://saashup.com for more information.\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Manage Docker with Netbox & style.",
    "version": "1.6.1",
    "project_urls": {
        "Bug Tracker": "https://github.com/SaaShup/netbox-docker-plugin/issues",
        "Homepage": "https://github.com/SaaShup/netbox-docker-plugin"
    },
    "split_keywords": [
        "netbox",
        " netbox-plugin",
        " docker"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "868e98ef146cb2d35922dc39cf47fe482c2db67401c90276456397c8c02f3ae3",
                "md5": "dccf026694f42126340296fe2ba8552c",
                "sha256": "edd5eb808b0ab158bae4d3aab0761fbeb5dfa0369265f8a37f076814ec8db658"
            },
            "downloads": -1,
            "filename": "netbox_docker_plugin-1.6.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "dccf026694f42126340296fe2ba8552c",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 78952,
            "upload_time": "2024-04-22T12:20:06",
            "upload_time_iso_8601": "2024-04-22T12:20:06.055204Z",
            "url": "https://files.pythonhosted.org/packages/86/8e/98ef146cb2d35922dc39cf47fe482c2db67401c90276456397c8c02f3ae3/netbox_docker_plugin-1.6.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "0f13420515970eb4bda3cbbf797ae84bb529278852b710bacc46eaf8c901d094",
                "md5": "c2900481af33e054846aca24f12f19b1",
                "sha256": "927fd8c6f081110f38376f255dc71568baea5ebaa87953223eacd2f8bad378e2"
            },
            "downloads": -1,
            "filename": "netbox_docker_plugin-1.6.1.tar.gz",
            "has_sig": false,
            "md5_digest": "c2900481af33e054846aca24f12f19b1",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 36870,
            "upload_time": "2024-04-22T12:20:07",
            "upload_time_iso_8601": "2024-04-22T12:20:07.898229Z",
            "url": "https://files.pythonhosted.org/packages/0f/13/420515970eb4bda3cbbf797ae84bb529278852b710bacc46eaf8c901d094/netbox_docker_plugin-1.6.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-04-22 12:20:07",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "SaaShup",
    "github_project": "netbox-docker-plugin",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "netbox-docker-plugin"
}
None
Elapsed time: 0.25202s