NetBox Custom Objects Quickstart guide

Author: mrmrcoleman

custom-objects-quickstart/.gitignore

@@ -0,0 +1,2 @@
+netbox-docker/
+environment

custom-objects-quickstart/1_set_envvars.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+ENV_FILE="environment"
+
+# Check if the environment file exists
+if [ -f "$ENV_FILE" ]; then
+    echo "Environment file found. Using existing variables."
+else
+    echo "Environment file not found. Generating new variables."
+
+    if [[ -z "${MY_EXTERNAL_IP}" ]]; then
+	# Attempt to fetch the external IPv4 address
+    	EXTERNAL_IP=$(curl -4 -s ifconfig.me)  # Use -4 to ensure IPv4 is returned
+    	# Check if the IP was retrieved successfully
+    	if [ -z "$EXTERNAL_IP" ]; then
+        	echo "Error: Unable to determine external IPv4 address."
+        	exit 1
+    	fi
+    else
+	EXTERNAL_IP=${MY_EXTERNAL_IP}
+    fi
+
+    # Generate new variables
+    MY_EXTERNAL_IP=$EXTERNAL_IP
+    NETBOX_PORT="8000"
+    NETBOX_TOKEN="1234567890"
+
+    # Write variables to the environment file
+    cat <<EOF > "$ENV_FILE"
+MY_EXTERNAL_IP=$MY_EXTERNAL_IP
+NETBOX_PORT=$NETBOX_PORT
+NETBOX_TOKEN=$NETBOX_TOKEN
+EOF
+fi
+
+# Export variables from the environment file
+while IFS='=' read -r key value; do
+    export "$key=$value"
+done < "$ENV_FILE"
+
+# Debug information to communicate values being used
+echo
+echo "--- Environment Variables Set ---"
+echo "External IP: $MY_EXTERNAL_IP"
+echo "NetBox will be deployed at: http://$MY_EXTERNAL_IP:$NETBOX_PORT"
+echo "NetBox username: admin"
+echo "NetBox password: admin"
+echo "NetBox token: $NETBOX_TOKEN"
+echo "-----------------------------------"

custom-objects-quickstart/2_start_netbox.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+set -euo pipefail
+
+# Check if all required environment variables are set
+REQUIRED_VARS=("MY_EXTERNAL_IP" "NETBOX_PORT" "NETBOX_TOKEN")
+
+for var in "${REQUIRED_VARS[@]}"; do
+  if [ -z "${!var:-}" ]; then
+    echo "Error: Required environment variable '$var' is not set."
+    exit 0
+  fi
+done
+
+echo
+echo "--- Cloning NetBox Docker ---"
+echo
+
+# Clone netbox-docker
+git clone --branch 3.3.0 https://github.com/netbox-community/netbox-docker.git
+pushd netbox-docker
+
+echo
+echo "--- Generating configuration files ---"
+echo
+
+# Create Dockerfile for plugins
+cat <<EOF > Dockerfile-Plugins
+FROM netboxcommunity/netbox:v4.3-3.3.0
+
+RUN uv pip install netboxlabs-netbox-custom-objects
+EOF
+
+cat <<EOF > docker-compose.override.yml
+services:
+  netbox:
+    image: netbox:v4.3-3.3.0-plugins
+    pull_policy: never
+    ports:
+      - "${NETBOX_PORT}:8080"
+    build:
+      context: .
+      dockerfile: Dockerfile-Plugins
+    environment:
+      SKIP_SUPERUSER: "false"
+      SUPERUSER_API_TOKEN: ${NETBOX_TOKEN}
+      SUPERUSER_EMAIL: ""
+      SUPERUSER_NAME: "admin"
+      SUPERUSER_PASSWORD: "admin"
+    healthcheck:
+      test: curl -f http://${MY_EXTERNAL_IP}:${NETBOX_PORT}/login/ || exit 1
+      start_period: 600s
+      timeout: 3s
+      interval: 15s
+  netbox-worker:
+    image: netbox:v4.3-3.3.0-plugins
+    pull_policy: never
+  netbox-housekeeping:
+    image: netbox:v4.3-3.3.0-plugins
+    pull_policy: never
+EOF
+
+# Add the NetBox Service Mappings plugin
+cat <<EOF > configuration/plugins.py
+PLUGINS = ["netbox_custom_objects"]
+EOF
+
+echo
+echo "--- Building NetBox ---"
+echo
+
+docker compose build --no-cache
+
+echo
+echo "--- Starting NetBox Docker ---"
+echo
+
+docker compose up -d
+
+# End
+popd
+echo "You can now access NetBox here: http://${MY_EXTERNAL_IP}:${NETBOX_PORT}"
+echo "username: admin"
+echo "password: admin"

custom-objects-quickstart/README.md

@@ -0,0 +1,59 @@
+# NetBox Custom Objects - Quickstart
+
+This simple repo is intended to get you up and running with NetBox Custom Objects quickly, using NetBox Docker.
+
+## Quick Setup
+
+## Prerequisites
+- Docker
+- Python 3.8 or higher
+
+### Setup
+
+1. Clone this repository:
+```bash
+git clone https://github.com/netboxlabs/netbox-learning.git
+cd custom-object-testing
+```
+
+2. Set up your environment:
+
+[!NOTE]
+> By default NetBox will be exposed on your **external** IP address which will not work in most home environments.  
+> To override this set the `EXTERNAL_IP` variable as shown below. `127.0.0.1` usually works, otherwise choose a local interface IP.
+
+```bash
+# OPTIONAL: Set IP address
+export EXTERNAL_IP=127.0.0.1
+
+# Set up environment variables
+source 1_set_envvars.sh
+```
+
+
+3. Start NetBox with Custom Objects
+
+```bash
+# Start NetBox instance
+./2_start_netbox.sh
+```
+
+### Notes
+
+- Environment variables are written into `environment`. To start from fresh:
+
+```bash
+# delete the environment file
+rm environment
+
+# Stop NetBox and clean up temporary files
+cd netbox-docker
+docker compose down
+cd ..
+rm -fr netbox-docker
+
+# Then go to step 2
+```
+
+- The time taken for NetBox to start up depends greatly on the available hardware. The timeout is set to 600 seconds. You can change this in `2_start_netbox.sh`.
+- The latest available version of NetBox Custom Objects will be used. You can edit `2_start_netbox.sh` to change this behaviour.