Skip to content

🏷️ Netbox

(Written May 2025)

Abstract

How to install Nebox, a self-hosted tool to document your homelab.

Prerequisites

Hardware requirements

  • RAM: Minimum 1 GB, recommended 2 GB+.
  • CPU: Minimum 1 core, recommended 2+ cores.
  • Storage: Minimum 20 Gb (depends on the size of your environment)

Install Netbox

Step 1: PostgreSQL Database

Update your system package list: 

sudo apt update
Install PostgreSQL: 
sudo apt install -y postgresql
Check the installed PostgreSQL version (v14 or later required): 
psql -V
Log into the PostgreSQL prompt as the default postgres user: 
sudo -u postgres psql
Create the NetBox database: 
CREATE DATABASE netbox;

Warning

Please make sure that your database is using 'UTF8' and NOT 'SQL_ASCII'. You can check by using the command: 

\l netbox

You should see something like: Name | Owner | Encoding | ... --------+--------+----------+---- netbox | netbox | UTF8 | ...

On my Proxmox LXC I had to use the following command to use UTF8

CREATE DATABASE netbox ENCODING 'UTF8' TEMPLATE template0;

Create a PostgreSQL user and assign ownership of the database: 

CREATE USER netbox WITH PASSWORD 'YourSuperSecurePassword';
ALTER DATABASE netbox OWNER TO netbox;
\connect netbox;
GRANT CREATE ON SCHEMA public TO netbox;
\q

Step 2: Redis

Install Redis, which NetBox uses for caching and background tasks: 

sudo apt install -y redis-server
Test if the Redis service is responding: 
redis-cli ping

Step 3: Netbox

Install system dependencies required by NetBox: 

sudo apt install -y python3 python3-pip python3-venv python3-dev \
build-essential libxml2-dev libxslt1-dev libffi-dev libpq-dev \
libssl-dev zlib1g-dev
Create a directory for NetBox: 
sudo mkdir -p /opt/netbox/
cd /opt/netbox/
Install Git: 
sudo apt install -y git
Clone the official NetBox repository: 
sudo git clone https://github.com/netbox-community/netbox.git .

Create a dedicated system user for NetBox: 

sudo adduser --system --group netbox
Set ownership for important NetBox directories: 
sudo chown --recursive netbox /opt/netbox/netbox/media/
sudo chown --recursive netbox /opt/netbox/netbox/reports/
sudo chown --recursive netbox /opt/netbox/netbox/scripts/
Generate a secret key for your NetBox installation: 
/opt/netbox/netbox/generate_secret_key.py
Edit the main configuration file: 
nano /opt/netbox/netbox/netbox/configuration.py
Example configuration file snippet with highlights:
configuration.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
# Example: ALLOWED_HOSTS = ['netbox.example.com', 'netbox.internal.local']
ALLOWED_HOSTS = ['IP addr of your VM']

# PostgreSQL database configuration. See the Django documentation for a complete list of available parameters:
#   https://docs.djangoproject.com/en/stable/ref/settings/#databases
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',  # Database engine
        'NAME': 'netbox',         # Database name
        'USER': 'netbox',               # PostgreSQL username
        'PASSWORD': 'YourSuperSecretPassword',           # PostgreSQL password
        'HOST': 'localhost',      # Database server
        'PORT': '',               # Database port (leave blank for default)
        'CONN_MAX_AGE': 300,      # Max database connection age
    }
}

# Redis database settings. Redis is used for caching and for queuing background tasks such as webhook events. A separate
# configuration exists for each. Full connection details are required in both sections, and it is strongly recommended
# to use two separate database IDs.
REDIS = {
    'tasks': {
        'HOST': 'localhost',
        'PORT': 6379,
        # Comment out `HOST` and `PORT` lines and uncomment the following if using Redis Sentinel
        # 'SENTINELS': [('mysentinel.redis.example.com', 6379)],
        # 'SENTINEL_SERVICE': 'netbox',
        'USERNAME': '',
        'PASSWORD': '',
        'DATABASE': 0,
        'SSL': False,
        # Set this to True to skip TLS certificate verification
        # This can expose the connection to attacks, be careful
        # 'INSECURE_SKIP_TLS_VERIFY': False,
        # Set a path to a certificate authority, typically used with a self signed certificate.
        # 'CA_CERT_PATH': '/etc/ssl/certs/ca.crt',
    },
    'caching': {
        'HOST': 'localhost',
        'PORT': 6379,
        # Comment out `HOST` and `PORT` lines and uncomment the following if using Redis Sentinel
        # 'SENTINELS': [('mysentinel.redis.example.com', 6379)],
        # 'SENTINEL_SERVICE': 'netbox',
        'USERNAME': '',
        'PASSWORD': '',
        'DATABASE': 1,
        'SSL': False,
        # Set this to True to skip TLS certificate verification
        # This can expose the connection to attacks, be careful
        # 'INSECURE_SKIP_TLS_VERIFY': False,
        # Set a path to a certificate authority, typically used with a self signed certificate.
        # 'CA_CERT_PATH': '/etc/ssl/certs/ca.crt',
    }
}

# This key is used for secure generation of random numbers and strings. It must never be exposed outside of this file.
# For optimal security, SECRET_KEY should be at least 50 characters in length and contain a mix of letters, numbers, and
# symbols. NetBox will not run without this defined. For more information, see
# https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-SECRET_KEY
SECRET_KEY = 'YourSecretKey'
Run the NetBox upgrade/install script: 
sudo /opt/netbox/upgrade.sh
Set up automatic daily housekeeping: 
sudo ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping
Activate the virtual environment to test NetBox manually: 
source /opt/netbox/venv/bin/activate
Run NetBox in development mode to verify it's working: 
python3 manage.py runserver 0.0.0.0:8000 --insecure
Deactivate the virtual environment after testing: 
deactivate

Step 4: Gunicorn

Copy the Gunicorn config file: 

sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
Copy the systemd service unit files: 
sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
sudo systemctl daemon-reload
Enable and start the NetBox services: 
sudo systemctl enable --now netbox netbox-rq
Check the service status: 
systemctl status netbox.service

Step 5: NGINX

Generate a self-signed TLS certificate: 

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout /etc/ssl/private/netbox.key \
-out /etc/ssl/certs/netbox.crt
Install the NGINX web server: 
sudo apt install -y nginx
Copy the NetBox-provided NGINX config file: 
sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox
Disable the default NGINX site and enable the NetBox config: 
sudo rm /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox
Restart NGINX to apply changes: 
sudo systemctl restart nginx