Setting up NetBox with a managed PostgreSQL database

• netbox
• dcim
• ipam
• database

Netbox - Overview

NetBox is a web application designed and built to help manage and document large computer networks. It is designed for IP address management (IPAM) and data center infrastructure management (DCIM). The application runs as a web application based on the Django Python framework and uses a PostgreSQL database to store information. The open source software was developed specifically with the needs of network and infrastructure engineers in mind.

In this tutorial, you will learn how to install and configure NetBox on a Virtual Instance running on Ubuntu 20.04 LTS and a Managed Database for PostgreSQL.

Configuring the database

NetBox requires a PostgreSQL database. Configure your Managed Database for PostgreSQL with a few steps from your Scaleway console

1. Enter the Databases section of your Scaleway console by clicking on Databases in the side menu.

2. Click the name of the Managed Database you want to use to view the instance’s details:

   

3. Click the Databases tab to view the databases of your instance.

   

4. Click + Add Database. The new database dialog appears.

5. Enter the name for the new database (netbox) and click Create Database to launch the database creation:

   

6. Select the Users tab to view the users of your Database Instance.

7. Click + Add user to create a new netbox user for the database. Enter the identifier and password for the user:

   

8. Then click the Permissions tab and set ALL permissions for the user on the netbox table.

9. Once done, click Create a user to validate the form and launch the user creation process:

   

Installing NetBox

1. Log into your instance using SSH.

2. Update the apt package cache and upgrade the software already installed on the instance to the latest version available in Ubuntu’s repositories:

   apt update && apt upgrade -y
   Copy code

3. Install the required packages using the apt package manager:

   apt install -y libpq-dev python3 python3-pip python3-dev python3-venv build-essential libxml2-dev libxslt1-dev libffi-dev graphviz libpq-dev libssl-dev redis-server zlib1g-dev git nginx
   Copy code

4. Download the latest release of NetBox. At the time of writing this tutorial it is version 2.10.3 and unpack it into the /opt directory:

   wget https://github.com/netbox-community/netbox/archive/v2.10.3.tar.gz && tar -xzf v2.10.3.tar.gz -C /opt
   Copy code

5. Create a symlink from the actual netbox directory to /opt/netbox:

   ln -s /opt/netbox-2.10.3/ /opt/netbox
   Copy code

6. Create a new system user for the NetBox application:

   adduser --system --group netbox
   Copy code

7. Set the ownership of the /opt/netbox/netbox/media/ to the netbox user. This is important as otherwise NetBox will not be able to write in this directory and you will not be able to upload any documents or images.

   chown --recursive netbox /opt/netbox/netbox/media/
   Copy code

8. Move into the NetBox configuration directory:

   cd /opt/netbox/netbox/netbox/
   Copy code

9. Make a copy of configuration.example.py and name it configuration.py:

   cp configuration.example.py configuration.py
   Copy code

10. Open the configuration file in a text editor of your choice, e.g. nano:

    nano configuration.py
    Copy code

11. Edit the variables ALLOWED_HOSTS, DATABASE, REDIS, SECRET_KEY as following:

• ALLOWED_HOSTS specifies the hostnames or IP-addresses that are used for the NetBox instance:

  ALLOWED_HOSTS = ['netbox.example.com', '198.51.100.35']
  Copy code

• DATABASE specifies the database credentials of your PostgreSQL database. Use the database netbox with the credentials of the netbox user previously created. You can find the required database host and port on the Instance Information in your Scaleway Elements Console.

  DATABASE = {
      'NAME': 'netbox',                             # Database name
      'USER': 'netbox',                             # PostgreSQL username
      'PASSWORD': '<YOUR_DATABASE_USER_PASSWORD>',  # PostgreSQL password
      'HOST': '<YOUR_RDB_IP>',                      # Database server IP (available in your Scaleway Elements console)
      'PORT': '<YOUR_RDB_PORT>',                    # Database port (available in your Scaleway Elements console)
      'CONN_MAX_AGE': 300,                          # Maximum database connection age
  }
  Copy code

• REDIS specifies the configuration parameters of Redis, an in-memory key-value store required as part of the NetBox installation. For most installations the default configuration is good enough and you can leave it as it is. For more information about advanced Redis configuration, you may refer to the official documentation.

• SECRET_KEY specifies a secret cryptographic key that is used to improve the security of cookies and password resets. It should be at least 50 characters long and should not be shared outside the configuration file. You may change the value of the key at any time, resulting in a termination of all active sessions.

Enter the key in the configuration file as follows, then save the file and exit your text editor:

SECRET_KEY = 'uyK5ajt-Vl$!gd2HeLbN=^6@&EhDmv8%)zT1S03kXPCsUGrI9_'
Copy code

python3 /opt/netbox/netbox/generate_secret_key.py
Copy code

12. Once NetBox has been configured, proceed with the actual installation by running the packaged upgrade script (upgrade.sh):

    /opt/netbox/upgrade.sh
    Copy code

This script performs the following actions on your instance:

• Creating a Python virtual environment
• Installing all required Python packages
• Running database schema migrations
• Aggregating static resource files on disk

The basic configuration for NetBox is done now, several other configuration options are available but optional. Refer to the official documentation for more information on them.

Creating a superuser

NetBox does not come with any default user accounts. Create a first user by completing the following steps:

1. Enter the NetBox venv created by the installation script:

   source /opt/netbox/venv/bin/activate
   Copy code

2. Enter into the netbox directory:

   cd /opt/netbox/netbox
   Copy code

3. Run the manage.py script as follows:

   python3 manage.py createsuperuser
   Copy code

Enter the username, email, password, and password confirmation for the user and confirm by pressing Enter. The following message displays once the user is created: Superuser created successfully.

Testing the application

1. Run the following command to start a test webserver with the NetBox application:

   python3 manage.py runserver 0.0.0.0:8000 --insecure
   Copy code

2. Open a web browser and point it to the IP address or hostname of your instance on port 8000: http://netbox.example.com:8000. The NetBox dashboard displays.

3. Terminate the test webserver by pressing CTRL+ C.

Configuring gunicorn

gunicorn is a Python WSGI HTTP Server for UNIX which will be used to serve the NetBox application to Nginx.

1. Copy the gunicorn configuration file from the contrib directory to its final destination:

   cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn_config.py
   Copy code

The configuration file shipped with the NetBox application works for most setups, however if you need some specific settings, refer to the gunicorn documentation.

Configuring systemd

We use systemd to start NetBox automatically during the boot process of the instance.

1. Copy the systemd scripts from the contrib directory to their final location:

   cp /opt/netbox/contrib/*.service /etc/systemd/system/
   Copy code

2. Reload they systemd daemon:

   systemctl daemon-reload
   Copy code

3. Start and enable the netbox-rq service

   systemctl start netbox netbox-rq
   systemctl enable netbox netbox-rq
   Copy code

Configuring a NGINX Reverse Proxy

To provide an additional layer of security, NetBox will be running behind a NGINX reverse proxy. This proxy replies to all requests to NetBox and avoids exposing the application directly on the Internet.

1. Create and open the file /etc/nginx/sites-available/netbox.conf in a text editor of your choice, i.e. nano:

   nano /etc/nginx/sites-available/netbox.conf
   Copy code

2. Copy the following configuration into the file /etc/nginx/sites-available/netbox.conf. Make sure to replace netbox.example.com with the hostname of your instance.

   server {
       listen 80;
   
       # CHANGE THIS TO YOUR SERVER'S NAME
       server_name netbox.example.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;
       }
   }
   Copy code

Save the file and exit the text editor.

3. Create a symlink to enable the new configuration with NGINX:

   ln -s /etc/nginx/sites-available/netbox.conf /etc/nginx/sites-enabled/netbox.conf
   Copy code

4. Reload NGINX to activate the new configuration:

   service nginx reload
   Copy code

5. Install certbot to configure a TLS encrypted connection to your NetBox instance:

   apt install certbot python3-certbot-nginx
   Copy code

6. Run certbot to request a TSL/SSL certificate for your NetBox instance, issued by the Let’s Encrypt certificate authority:

   certbot --nginx
   Copy code

Follow our dedicated documentation about Let’s Encrypt for detailed information how to use the certbot tool.

7. Open your web browser and point it to your NetBox domain (i.e. http://netbox.example.com). The Netbox dashboard displays:
   

You can log into Netbox by clicking on the Log In button in the top right corner using the username and password of the superuser configured in a previous step.

Conclusion

You now have successfully installed Netbox and linked it with a managed PostgreSQL database. The application is now ready to be configured. You can add your servers, racks and other network equipment directly from the NetBox webinterface.

For more information how to add your devices to NetBox, refer to the official documentation.