How to install Netbox with Apache and uWSGI

Netbox is an IPAM and DCIM tool written by Jeremy Stretch¹ for the DigitalOcean’s needs.

It was released in June 2016, and has since become (in my opinion) the best FLOSS tool to manage your inventory of network devices, servers, IP addresses and their interconnections².

Here I’ll describe how to install Netbox using uWSGI and Apache mod_proxy_uwsgi on Debian³. I won’t cover what Netbox’s documentation already does (Netbox’s code or PostgreSQL installation and configuration for instance), I’ll assume that you already followed the official documentation to download Netbox, install its dependencies and configure everything (tip: the upgrade.sh script at the root of the repository does all this for you).

If you only want to get the configuration files and avoid reading all the crap I write, you can look at this Github Gist I made a few month ago.

Setting up uWSGI

The first thing to do when you’ve setup Netbox is to install and configure uWSGI. There’s nothing tricky here, just install it along with its Python 3 plugin using your package manager:

# apt-get install uwsgi uwsgi-plugin-python3

Then you’ll notice two subdirectories in /etc/uwsgi: the apps-available directory where you’ll store your configuration file for each “applications” (Netbox is one of those) and the apps-enabled where you’ll create symlinks to the former configuration files.

The uWSGI configuration isn’t too complex as Django (the Python framework used by Netbox) provides out of the box integration with WSGI softwares:

[uwsgi]
project = netbox

plugins = python3

base = /opt/netbox/
chdir = %(base)/%(project)
module = %(project).wsgi:application

socket = 127.0.0.1:8000

master = True
processes = 4
vacuum = True

Here, we’re telling uWSGI that we’re working with Python 3 and that it must look for an object named application in a module called netbox.wsgi in the /opt/netbox/netbox directory. This is a pretty standard Django application configuration.

The socket option tells uWSGI how Apache will comminucate with it. You might want to set a path to a uniw socket here, or even don’t set the option. In thi case, the default uWSGI socket for your application will be created in /run/uwsgi/app/netbox/socket.

I can’t give you recomandations on how to tweak the processes settings, but feel free to set it up so it answer to your needs. In my small setup, beeing the only user, four processes is more than enough.

You may also want to use Python virtualenv to install Netbox so that you don’t mess with your system’s Python installation. In that case you just need add the following line anywhere in your uWSGI configuration file:

virtualenv = /path/to/your/virtualenv

Once everything is set up as you want to, create a symlink in apps-enabled and restart uWSGI:

# ln -s ../apps-available/netbox /etc/uwsgi/apps-enabled/netbox
# systemctl restart uwsgi

Setting up Apache as a reverse proxy

The next thing to do is to install and set up Apache with mod_proxy_wsgi. I won’t cover the details of the base configuration of Apache, I’ll only focus on how to make Netbox work.

# apt-get install apache2 libapache2-mod-proxy-uwsgi
# a2enmod proxy_uwsgi

Apache configuration is really simple, you only need a VirtualHost with a ProxyPass to the uwSGI socket:

<VirtualHost *:80>
  ServerName netbox.example.org

  ProxyPass /media !
  ProxyPass /static !
  ProxyPass / uwsgi://127.0.0.1:8000/

  Alias /media /opt/netbox/netbox/media
  Alias /static /opt/netbox/netbox/static

  <Directory ~ /opt/netbox/netbox/(media|static)>
    Require all granted
    Options Indexes FollowSymLinks MultiViews
    AllowOverride None
  </Directory>
</VirtualHost>

You don’t need to setup a document root here, as all the code will be executed by uWSGI. However media and static files should directly be served by Apache and not be managed by uWSGI, so we disable request proxying for these locations.

To use a unix socket for your ProxyPass, you need to use this syntax: ProxyPass unix://path/to/the/socket|uwsgi://netbox (see uWSGI documentation for details).

Then you must enable the new VirtualHost and restart Apache to reload its configuration:

# a2ensite <name of you vhost file>  # e.g netbox.conf
# systemctl restart apache

You can now enjoy your wonderful Netbox installation !

Serving netbox from a “subdirectory” (Optional)

You may also want to install Netbox as a “subdirectory” (e.g. https://exemple.com/netbox/) and according to the documentation, all you have to do is to set the BASE_PATH setting to the correct value (e.g. BASE_PATH = 'netbox/').

You’ll quickly find out that there’s some kind of bug with Apache mod_proxy_uwsgi leading Netbox to prepend the BASE_PATH value twice to every URL it generates.

To fix that you need to add these two route settings in your uWSGI configuration (change the path accordingly to what you set in BASE_PATH):

route = /(.*) setpathinfo:/netbox/$1
route = . setscriptname:/

Then adapt the paths in your Apache configuration accordingly.