Skip to content

Commit 819d90d

Browse files
jirivranyjirivrany
committed
updated README
1 parent 22f0854 commit 819d90d

File tree

1 file changed

+184
-30
lines changed

1 file changed

+184
-30
lines changed

‎README.md‎

Lines changed: 184 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,27 @@ A NetBox plugin for managing service paths and segments in network infrastructur
1515
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
1616
[![PyPI version](https://img.shields.io/pypi/v/cesnet-service-path-plugin.svg)](https://pypi.org/project/cesnet-service-path-plugin/)
1717
[![Python versions](https://img.shields.io/pypi/pyversions/cesnet-service-path-plugin.svg)](https://pypi.org/project/cesnet-service-path-plugin/)
18-
[![NetBox compatibility](https://img.shields.io/badge/NetBox-4.4-green.svg)](https://github.com/netbox-community/netbox)
18+
[![NetBox compatibility](https://img.shields.io/badge/NetBox-4.2%20|%204.3%20|%204.4-blue.svg)](https://github.com/netbox-community/netbox)
19+
20+
## 📑 Table of Contents
21+
22+
- [Overview](#overview)
23+
- [Compatibility Matrix](#compatibility-matrix)
24+
- [Features](#features)
25+
- [Data Model](#data-model)
26+
- [Installation and Configuration](#installation-and-configuration)
27+
- [Prerequisites](#prerequisites)
28+
- [Step-by-Step Installation](#step-1-enable-postgis-in-postgresql)
29+
- [Additional Configuration](#additional-configuration)
30+
- [Custom Status Choices](#custom-status-choices)
31+
- [Custom Kind Choices](#custom-kind-choices)
32+
- [Geographic Path Data](#geographic-path-data)
33+
- [API Usage](#api-usage)
34+
- [Development](#development)
35+
- [Navigation and UI](#navigation-and-ui)
36+
- [Troubleshooting](#troubleshooting)
37+
- [Credits](#credits)
38+
- [License](#license)
1939

2040
## Overview
2141

@@ -93,67 +113,201 @@ The CESNET ServicePath Plugin extends NetBox's capabilities by providing compreh
93113
- **Length calculation** using projected coordinates
94114
- **Source format tracking** (KML, KMZ, GeoJSON, manual)
95115

96-
## Quick Start
116+
## Installation and Configuration
117+
118+
⚠️ **Important**: This plugin requires PostGIS and geographic libraries. Standard NetBox installations need additional setup steps.
119+
120+
### Prerequisites
121+
122+
Before installing the plugin, ensure you have:
123+
124+
1. **PostgreSQL with PostGIS extension** (version 3.0 or higher recommended)
125+
2. **System libraries**: GDAL, GEOS, and PROJ
126+
3. **NetBox 4.2 or higher**
127+
128+
#### Installing System Dependencies
129+
130+
**Ubuntu/Debian:**
131+
```bash
132+
sudo apt-get update
133+
sudo apt-get install postgresql-15-postgis-3 gdal-bin libgdal-dev libgeos-dev libproj-dev
134+
```
135+
136+
**macOS:**
137+
```bash
138+
brew install postgresql postgis gdal geos proj
139+
```
140+
141+
**Docker users**: The official `netboxcommunity/netbox` images do **NOT** include PostGIS and GDAL libraries by default. You will need to create a custom Docker image. See the Docker-specific instructions below.
142+
143+
### Step 1: Enable PostGIS in PostgreSQL
144+
145+
Connect to your NetBox database and enable the PostGIS extension:
146+
147+
```sql
148+
-- Connect to your NetBox database
149+
\c netbox
150+
151+
-- Enable PostGIS extension
152+
CREATE EXTENSION IF NOT EXISTS postgis;
153+
154+
-- Verify installation
155+
SELECT PostGIS_version();
156+
```
157+
158+
### Step 2: Configure NetBox Database Engine
159+
160+
**CRITICAL**: Update your NetBox `configuration.py` to use the PostGIS database engine:
161+
162+
```python
163+
# Set the database engine to PostGIS
164+
DATABASE_ENGINE = "django.contrib.gis.db.backends.postgis"
165+
166+
# PostgreSQL database configuration
167+
DATABASE = {
168+
"ENGINE": DATABASE_ENGINE, # Must use PostGIS engine
169+
"NAME": environ.get("DB_NAME", "netbox"),
170+
"USER": environ.get("DB_USER", ""),
171+
"PASSWORD": read_secret("db_password", environ.get("DB_PASSWORD", "")),
172+
"HOST": environ.get("DB_HOST", "localhost"),
173+
"PORT": environ.get("DB_PORT", ""),
174+
"OPTIONS": {"sslmode": environ.get("DB_SSLMODE", "prefer")},
175+
"CONN_MAX_AGE": int(environ.get("DB_CONN_MAX_AGE", "300")),
176+
}
177+
```
178+
179+
**Note**: This is just an example. If you're using NetBox Docker, this can be configured via environment variables in your `docker-compose.yml` or similar configuration files.
180+
181+
### Step 3: Install the Plugin
182+
183+
#### Standard Installation (pip)
97184

98-
1. Install the plugin:
99185
```bash
100186
pip install cesnet_service_path_plugin
101187
```
102188

103-
2. Enable the plugin in your NetBox configuration:
189+
#### Docker Installation
190+
191+
The official NetBox Docker images do not include the required geographic libraries. You need to create a custom Docker image.
192+
193+
**Option 1: Create a Custom Dockerfile**
194+
195+
Create a `Dockerfile` extending the official NetBox image:
196+
197+
```dockerfile
198+
FROM netboxcommunity/netbox:v4.4
199+
200+
# Install PostGIS and geographic libraries
201+
RUN apt-get update && \
202+
apt-get install -y --no-install-recommends \
203+
postgresql-client \
204+
postgis \
205+
gdal-bin \
206+
libgdal-dev \
207+
libgeos-dev \
208+
libproj-dev \
209+
python3-gdal \
210+
&& rm -rf /var/lib/apt/lists/*
211+
212+
# Copy plugin requirements
213+
COPY plugin_requirements.txt /opt/netbox/
214+
RUN /opt/netbox/venv/bin/pip install --no-cache-dir -r /opt/netbox/plugin_requirements.txt
215+
```
216+
217+
Then create a `plugin_requirements.txt` file:
218+
```
219+
cesnet_service_path_plugin
220+
```
221+
222+
Build your custom image:
223+
```bash
224+
docker build -t netbox-with-gis:latest .
225+
```
226+
227+
Update your `docker-compose.yml` to use the custom image:
228+
```yaml
229+
services:
230+
netbox:
231+
image: netbox-with-gis:latest
232+
# ... rest of your configuration
233+
```
234+
235+
**Option 2: Use docker-compose override**
236+
237+
Add a `docker-compose.override.yml` file:
238+
239+
```yaml
240+
version: '3.8'
241+
services:
242+
netbox:
243+
build:
244+
context: .
245+
dockerfile: Dockerfile.custom
246+
```
247+
248+
For detailed Docker setup instructions, see [using netbox-docker with plugins](https://github.com/netbox-community/netbox-docker/wiki/Using-Netbox-Plugins).
249+
250+
### Step 4: Enable the Plugin
251+
252+
Add the plugin to your NetBox `configuration.py`:
253+
104254
```python
105255
PLUGINS = [
106-
'cesnet_service_path_plugin'
256+
'cesnet_service_path_plugin',
107257
]
108258
109259
PLUGINS_CONFIG = {
110260
"cesnet_service_path_plugin": {},
111261
}
112262
```
113263

114-
3. Run NetBox migrations:
264+
### Step 5: Run Database Migrations
265+
266+
Apply the plugin's database migrations:
267+
115268
```bash
116-
python manage.py migrate
269+
cd /opt/netbox/netbox
270+
source venv/bin/activate
271+
python manage.py migrate cesnet_service_path_plugin
117272
```
118273

119-
4. **Configure GeoDjango** (required for geographic features):
120-
- Install GDAL, GEOS, and PROJ libraries
121-
- Configure PostGIS extension in PostgreSQL
122-
- See [GeoDjango installation guide](https://docs.djangoproject.com/en/stable/ref/contrib/gis/install/)
123-
124-
## Installation
274+
**Docker users:**
275+
```bash
276+
docker exec -it netbox python /opt/netbox/netbox/manage.py migrate cesnet_service_path_plugin
277+
```
125278

126-
### Prerequisites
279+
### Step 6: Restart NetBox
127280

128-
For geographic features, you need:
129-
- **PostGIS-enabled PostgreSQL database**
130-
- **GDAL, GEOS, and PROJ libraries**
131-
- **Python packages**: `geopandas`, `fiona`, `shapely`
281+
Restart your NetBox services to load the plugin:
132282

133-
### Using pip
134283
```bash
135-
pip install cesnet_service_path_plugin
284+
sudo systemctl restart netbox netbox-rq
136285
```
137286

138-
### Using Docker
139-
For NetBox Docker installations, add to your `plugin_requirements.txt`:
287+
**Docker users:**
140288
```bash
141-
cesnet_service_path_plugin
289+
docker-compose restart netbox netbox-worker
142290
```
143291

144-
**Docker users**: Ensure your NetBox Docker image includes PostGIS and GDAL libraries.
292+
### Verification
145293

146-
For detailed Docker setup instructions, see [using netbox-docker with plugins](https://github.com/netbox-community/netbox-docker/wiki/Using-Netbox-Plugins).
294+
To verify the installation:
147295

148-
## Configuration
296+
1. Log into NetBox
297+
2. Check that "Service Paths" appears in the navigation menu
298+
3. Navigate to **Service Paths → Segments** to confirm the plugin is working
149299

150-
### Database Configuration
300+
For geographic feature verification, you can use the diagnostic function in the Django shell:
151301

152-
Ensure your NetBox database has PostGIS enabled:
153-
```sql
154-
CREATE EXTENSION IF NOT EXISTS postgis;
302+
```python
303+
python manage.py nbshell
304+
305+
from cesnet_service_path_plugin.utils import check_gis_environment
306+
check_gis_environment()
155307
```
156308

309+
## Additional Configuration
310+
157311
### Custom Status Choices
158312

159313
Extend or override default status choices in your `configuration.py`:

0 commit comments

Comments
 (0)