NetBox Installation Guide

6 October 2025 · Updated 6 October 2025

NetBox is an open-source IPAM and DCIM tool — the source of truth for “what’s connected to what” in a network. This note is a straight installation walkthrough on Ubuntu (or close equivalent) with PostgreSQL, Redis, Gunicorn, and NGINX as the public-facing layer.

Requirements

System Requirements

Minimum:

1 CPU Core
2 GB RAM
40 GB Storage

Recommended:

2 CPU Cores
4 GB RAM
80 GB Storage

Software Requirements

Package	Version
Python	3.10, 3.11, 3.12
PostgreSQL	12+
Redis	4.0+

Supported Operating Systems

Ubuntu Server 22.04 LTS / 24.04 LTS (recommended)
CentOS / RHEL 8+
Debian 11+

Installation Steps

1. Install PostgreSQL

Ubuntu/Debian:

sudo apt update
sudo apt install -y postgresql

Verify version:

psql -V  # Should be 12 or later

2. Create NetBox Database

Switch to postgres user and create database:

sudo -u postgres psql

In the PostgreSQL shell:

CREATE DATABASE netbox;
CREATE USER netbox WITH PASSWORD 'your_secure_password';
ALTER DATABASE netbox OWNER TO netbox;

-- For PostgreSQL 15+, grant schema permissions
\connect netbox;
GRANT CREATE ON SCHEMA public TO netbox;

Exit with \q.

Test database connection:

psql --username netbox --password --host localhost netbox

Type the password when prompted. If successful, you’ll see the netbox=> prompt.

3. Install Redis

Ubuntu/Debian:

sudo apt install -y redis-server

Verify version:

redis-server -v  # Should be 4.0 or later

Test Redis:

redis-cli ping

Expected response: PONG

4. Install Python Dependencies

Ubuntu/Debian:

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 git

Verify Python version:

python3 -V  # Should be 3.10, 3.11, or 3.12

5. Download NetBox

Create installation directory:

sudo mkdir -p /opt/netbox/
cd /opt/netbox/

Clone the repository (master branch = stable release):

sudo git clone -b master --depth 1 https://github.com/netbox-community/netbox.git .

6. Create NetBox System User

sudo groupadd --system netbox
sudo adduser --system -g netbox netbox
sudo chown --recursive netbox /opt/netbox/netbox/media/
sudo chown --recursive netbox /opt/netbox/netbox/reports/
sudo chown --recursive netbox /opt/netbox/netbox/scripts/

7. Configure NetBox

Navigate to configuration directory:

cd /opt/netbox/netbox/netbox/
sudo cp configuration_example.py configuration.py

Edit the configuration:

sudo vim configuration.py

Required settings:

# Allowed hostnames/IPs
ALLOWED_HOSTS = ['netbox.yourdomain.com', '192.168.1.100']

# Database configuration
DATABASE = {
    'NAME': 'netbox',
    'USER': 'netbox',
    'PASSWORD': 'your_secure_password',
    'HOST': 'localhost',
    'PORT': '',
    'CONN_MAX_AGE': 300,
}

# Redis configuration
REDIS = {
    'tasks': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': '',
        'DATABASE': 0,
        'SSL': False,
    },
    'caching': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': '',
        'DATABASE': 1,
        'SSL': False,
    }
}

# Secret key (generate with: python3 ../generate_secret_key.py)
SECRET_KEY = 'your_generated_secret_key_here'

# Timezone
TIME_ZONE = 'UTC'  # Or your timezone, e.g., 'America/New_York'

Generate secret key:

python3 ../generate_secret_key.py

Copy the output and paste it into SECRET_KEY in configuration.py.

8. Run the Upgrade Script

The upgrade script creates the virtual environment, installs dependencies, and initializes the database:

sudo /opt/netbox/upgrade.sh

9. Create Superuser

Activate the virtual environment and create an admin user:

source /opt/netbox/venv/bin/activate
cd /opt/netbox/netbox
python3 manage.py createsuperuser

Follow the prompts to set username, email, and password.

10. Configure Gunicorn

Copy the default Gunicorn configuration:

sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py

Optionally edit to adjust bind address/port or workers:

sudo vim /opt/netbox/gunicorn.py

11. Setup Systemd Services

Copy service files:

sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
sudo systemctl daemon-reload

Enable and start services:

sudo systemctl enable --now netbox netbox-rq

Verify services are running:

systemctl status netbox.service
systemctl status netbox-rq.service

12. Setup NGINX Reverse Proxy

Install NGINX:

sudo apt install -y nginx

Copy NetBox NGINX configuration:

sudo cp /opt/netbox/contrib/nginx.conf /etc/nginx/sites-available/netbox

Edit the configuration:

sudo vim /etc/nginx/sites-available/netbox

Basic configuration (HTTP only):

server {
    listen 80;
    server_name netbox.yourdomain.com;

    client_max_body_size 25m;

    location /static/ {
        alias /opt/netbox/netbox/static/;
    }

    location / {
        proxy_pass http://127.0.0.1:8001;
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/netbox /etc/nginx/sites-enabled/netbox
sudo rm /etc/nginx/sites-enabled/default  # Optional: remove default site

Test and restart NGINX:

sudo nginx -t
sudo systemctl restart nginx

SSL/TLS Configuration

Using Let’s Encrypt (Recommended)

Install certbot:

sudo apt install -y certbot python3-certbot-nginx

Obtain certificate:

sudo certbot --nginx -d netbox.yourdomain.com

Certbot will automatically configure NGINX for HTTPS.

Using Custom SSL Certificate

Generate self-signed certificate (testing only):

sudo mkdir -p /etc/nginx/ssl
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout /etc/nginx/ssl/netbox.key \
    -out /etc/nginx/ssl/netbox.crt

Using existing certificate:

If you have a wildcard or custom certificate:

# Extract from PFX/PKCS12
openssl pkcs12 -in certificate.pfx -clcerts -nokeys -out netbox.crt
openssl pkcs12 -in certificate.pfx -nocerts -out encrypted.key
openssl rsa -in encrypted.key -out netbox.key
rm encrypted.key

# Copy to NGINX directory
sudo mkdir -p /etc/nginx/ssl
sudo mv netbox.crt netbox.key /etc/nginx/ssl/
sudo chmod 600 /etc/nginx/ssl/netbox.key

NGINX HTTPS configuration:

server {
    listen 443 ssl http2;
    server_name netbox.yourdomain.com;

    ssl_certificate /etc/nginx/ssl/netbox.crt;
    ssl_certificate_key /etc/nginx/ssl/netbox.key;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384';
    ssl_prefer_server_ciphers on;

    client_max_body_size 25m;

    location /static/ {
        alias /opt/netbox/netbox/static/;
    }

    location / {
        proxy_pass http://127.0.0.1:8001;
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name netbox.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

Restart NGINX:

sudo systemctl restart nginx

Post-Installation

Access NetBox

Navigate to: http://netbox.yourdomain.com (or https:// if SSL configured)

Setup Housekeeping

Enable daily housekeeping tasks:

sudo ln -s /opt/netbox/contrib/netbox-housekeeping.sh /etc/cron.daily/netbox-housekeeping

Firewall Configuration

Ubuntu UFW:

sudo ufw allow 'Nginx HTTP'
sudo ufw allow 'Nginx HTTPS'

Firewalld (CentOS/RHEL):

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Upgrading NetBox

Check for latest version:

git ls-remote --tags https://github.com/netbox-community/netbox.git | grep -o 'refs/tags/v[0-9]*\.[0-9]*\.[0-9]*$' | tail -n 1 | sed 's|refs/tags/||'

Upgrade to specific version:

cd /opt/netbox
sudo git fetch --tags
sudo git checkout v4.1.0  # Replace with desired version
sudo ./upgrade.sh
sudo systemctl restart netbox netbox-rq

Backup and Restore

Database Backup

sudo -u postgres pg_dump netbox > netbox_backup_$(date +%Y%m%d).sql

Full Backup

# Database
sudo -u postgres pg_dump netbox | gzip > netbox_db_$(date +%Y%m%d).sql.gz

# Media files
sudo tar -czf netbox_media_$(date +%Y%m%d).tar.gz /opt/netbox/netbox/media/

# Configuration
sudo tar -czf netbox_config_$(date +%Y%m%d).tar.gz /opt/netbox/netbox/netbox/configuration.py

Restore

# Restore database
sudo -u postgres psql netbox &lt; netbox_backup.sql

# Restore media
sudo tar -xzf netbox_media.tar.gz -C /
sudo chown -R netbox /opt/netbox/netbox/media/

Troubleshooting

Check service status:

systemctl status netbox
systemctl status netbox-rq
systemctl status nginx

View logs:

# NetBox application logs
journalctl -u netbox -f

# NGINX logs
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log

Test NetBox directly (bypass NGINX):

sudo systemctl stop nginx
source /opt/netbox/venv/bin/activate
cd /opt/netbox/netbox
python3 manage.py runserver 0.0.0.0:8000 --insecure

Then access: http://server-ip:8000

Netbox Upgrade
Netbox Backup
Netbox Setup
Official docs: https://netboxlabs.com/docs/netbox/

NetBox Installation Guide

Requirements

System Requirements

Software Requirements

Supported Operating Systems

Installation Steps

1. Install PostgreSQL

2. Create NetBox Database

3. Install Redis

4. Install Python Dependencies

5. Download NetBox

6. Create NetBox System User

7. Configure NetBox

8. Run the Upgrade Script

9. Create Superuser

10. Configure Gunicorn

11. Setup Systemd Services

12. Setup NGINX Reverse Proxy

SSL/TLS Configuration

Using Let’s Encrypt (Recommended)

Using Custom SSL Certificate

Post-Installation

Access NetBox

Setup Housekeeping

Firewall Configuration

Upgrading NetBox

Backup and Restore

Database Backup

Full Backup

Restore

Troubleshooting

Related Documentation