= Installing NetBox on Ubuntu 20.04 = NetBox requires PostgreSQL 10 or later. Please note that MySQL and other relational databases are not supported. === PostgreSQL Database Installation === {{{ # sudo apt update # sudo apt install -y postgresql }}} Once PostgreSQL has been installed, start the service and enable it to run at boot: {{{ # sudo systemctl start postgresql # sudo systemctl enable postgresql }}} === Database Creation === At a minimum, we need to create a database for NetBox and assign it a username and password for authentication. Start by invoking the PostgreSQL shell as the system Postgres user. {{{ # sudo -u postgres psql }}} Within the shell, enter the following commands to create the database and user (role), substituting your own value for the password: {{{ CREATE DATABASE netbox; CREATE USER netbox WITH PASSWORD 'netbox123'; GRANT ALL PRIVILEGES ON DATABASE netbox TO netbox; }}} Do not use the password from the example. Choose a strong, random password to ensure secure database authentication for your NetBox installation. Once complete, enter ''' \q ''' to exit the PostgreSQL shell. === Redis Installation === Redis is an in-memory key-value store which NetBox employs for caching and queuing. This section entails the installation and configuration of a local Redis instance. Redis v4.0 or later required. {{{ # sudo apt install -y redis-server }}} Before continuing, verify that your installed version of Redis is at least v4.0: {{{ # redis-server -v }}} You may wish to modify the Redis configuration at ''' /etc/redis.conf ''' or ''' /etc/redis/redis.conf ''', however in most cases the default configuration is sufficient. {{{ # sudo systemctl start redis-server.service }}} Verify Service Status Use the ''' redis-cli ''' utility to ensure the Redis service is functional: {{{ # redis-cli ping }}} If successful, you should receive a ''' PONG ''' response from the server. == NetBox Installation == This section of the documentation discusses installing and configuring the NetBox application itself. === Install System Packages === Begin by installing all system packages required by NetBox and its dependencies. Python 3.8 or later required {{{ # 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 }}} Before continuing, check that your installed Python version is at least 3.8: {{{ # python3 -V }}} === Download NetBox === This documentation provides two options for installing NetBox: from a downloadable archive, or from the git repository. Installing from a package (option A below) requires manually fetching and extracting the archive for every future update, whereas installation via git (option B) allows for seamless upgrades by re-pulling the master branch. === Option A: Download a Release Archive === Download the latest stable release from GitHub as a tarball or ZIP archive and extract it to your desired path. In this example, we'll use ''' /opt/netbox ''' as the NetBox root. {{{ # sudo wget https://github.com/netbox-community/netbox/archive/vX.Y.Z.tar.gz # sudo tar -xzf vX.Y.Z.tar.gz -C /opt # sudo ln -s /opt/netbox-X.Y.Z/ /opt/netbox }}} === Option B: Clone the Git Repository === Create the base directory for the NetBox installation. For this guide, we'll use ''' /opt/netbox. ''' {{{ # sudo mkdir -p /opt/netbox/ # cd /opt/netbox/ }}} if ''' git ''' is not already installed, install it: {{{ # sudo apt install -y git }}} Next, clone the master branch of the NetBox GitHub repository into the current directory. (This branch always holds the current stable release.) {{{ sudo git clone -b master --depth 1 https://github.com/netbox-community/netbox.git . }}} The git clone command should generate output similar to the following: {{{ Cloning into '.'... remote: Enumerating objects: 996, done. remote: Counting objects: 100% (996/996), done. remote: Compressing objects: 100% (935/935), done. remote: Total 996 (delta 148), reused 386 (delta 34), pack-reused 0 Receiving objects: 100% (996/996), 4.26 MiB | 9.81 MiB/s, done. Resolving deltas: 100% (148/148), done. }}} === Create the NetBox System User === Create a system user account named ''' netbox '''. We'll configure the WSGI and HTTP services to run under this account. We'll also assign this user ownership of the media directory. This ensures that NetBox will be able to save uploaded files. {{{ # sudo adduser --system --group netbox # sudo chown --recursive netbox /opt/netbox/netbox/media/ }}} === Configuration === Move into the NetBox configuration directory and make a copy of ''' configuration_example.py ''' named ''' configuration.py.''' This file will hold all of your local configuration parameters. {{{ # cd /opt/netbox/netbox/netbox/ # sudo cp configuration_example.py configuration.py }}} Open ''' configuration.py ''' with your preferred editor to begin configuring NetBox. NetBox offers many configuration parameters, but only the following four are required for new installations: * ALLOWED_HOSTS * DATABASE * REDIS * SECRET_KEY === ALLOWED_HOSTS === This is a list of the valid hostnames and IP addresses by which this server can be reached. You must specify at least one name or IP address. (Note that this does not restrict the locations from which NetBox may be accessed: It is merely for HTTP host header validation.) {{{ # vim configuration.py ALLOWED_HOSTS = ['netbox.example.com', '192.0.2.123'] }}} If you are not yet sure what the domain name and/or IP address of the NetBox installation will be, you can set this to a wildcard (asterisk) to allow all host values: {{{ ALLOWED_HOSTS = ['*'] }}} === DATABASE === This parameter holds the database configuration details. You must define the username and password used when you configured PostgreSQL. If the service is running on a remote host, update the '''HOST and PORT ''' parameters accordingly. See the configuration documentation for more detail on individual parameters. {{{ DATABASE = { 'NAME': 'netbox', # Database name 'USER': 'netbox', # PostgreSQL username 'PASSWORD': 'netbox123', # PostgreSQL password 'HOST': 'localhost', # Database server 'PORT': '', # Database port (leave blank for default) 'CONN_MAX_AGE': 300, # Max database connection age (seconds) } }}}