= 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. 
{{{
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)
}
}}}

=== REDIS ===
Redis is a in-memory key-value store used by NetBox for caching and background task queuing. Redis typically requires minimal configuration; the values below should suffice for most installations. 

Note that NetBox requires the specification of two separate Redis databases: ''' tasks and caching.''' These may both be provided by the same Redis service, however each should have a unique numeric database ID.
{{{
REDIS = {
    'tasks': {
        'HOST': 'localhost',      # Redis server
        'PORT': 6379,             # Redis port
        'PASSWORD': '',           # Redis password (optional)
        'DATABASE': 0,            # Database ID
        'SSL': False,             # Use SSL (optional)
    },
    'caching': {
        'HOST': 'localhost',
        'PORT': 6379,
        'PASSWORD': '',
        'DATABASE': 1,            # Unique ID for second database
        'SSL': False,
    }
}
}}}
=== SECRET_KEY ===
This parameter must be assigned a randomly-generated key employed as a salt for hashing and related cryptographic functions. (Note, however, that it is never directly used in the encryption of secret data.) This key must be unique to this installation and is recommended to be at least 50 characters long. It should not be shared outside the local system.

A simple Python script named ''' generate_secret_key.py ''' is provided in the parent directory to assist in generating a suitable key:
{{{
# python3 ../generate_secret_key.py
}}}
When you have finished modifying the configuration, remember to save the file.

=== Run the Upgrade Script ===
Once NetBox has been configured, we're ready to proceed with the actual installation. We'll run the packaged upgrade script (upgrade.sh) to perform the following actions:

* Create a Python virtual environment
* Installs all required Python packages
* Run database schema migrations
* Builds the documentation locally (for offline use)
* Aggregate static resource files on disk

{{{
# sudo /opt/netbox/upgrade.sh
}}}
Note that Python 3.8 or later is required for NetBox v3.2 and later releases. 

=== Create a Super User ===
NetBox does not come with any predefined user accounts. You'll need to create a super user (administrative account) to be able to log into NetBox. First, enter the Python virtual environment created by the upgrade script:
{{{
# source /opt/netbox/venv/bin/activate
}}}
Once the virtual environment has been activated, you should notice the string ''' (venv) ''' prepended to your console prompt.

Next, we'll create a superuser account using the ''' createsuperuser ''' Django management command ''' (via manage.py) '''. Specifying an email address for the user is not required, but be sure to use a very strong password.
{{{
# cd /opt/netbox/netbox
# python3 manage.py createsuperuser
}}}
=== Test the Application ===
At this point, we should be able to run NetBox's development server for testing. We can check by starting a development instance:
{{{
# python3 manage.py runserver 0.0.0.0:8000 --insecure
}}}
If successful, you should see output similar to the following:
{{{
Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
August 30, 2021 - 18:02:23
Django version 3.2.6, using settings 'netbox.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.
}}}
Next, connect to the name or IP of the server (as defined in ALLOWED_HOSTS) on port 8000; for example, http://127.0.0.1:8000/. You should be greeted with the NetBox home page. Try logging in using the username and password specified when creating a superuser.

Type ''' Ctrl+c ''' to stop the development server.

=== Gunicorn ===
Like most Django applications, NetBox runs as a WSGI application behind an HTTP server. This documentation shows how to install and configure gunicorn (which is automatically installed with NetBox) for this role, however other WSGI servers are available and should work similarly well. uWSGI is a popular alternative.

''' Configuration '''

NetBox ships with a default configuration file for gunicorn. To use it, copy ''' /opt/netbox/contrib/gunicorn.py to /opt/netbox/gunicorn.py. '''(We make a copy of this file rather than pointing to it directly to ensure that any local changes to it do not get overwritten by a future upgrade.)

{{{
# sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
}}}

''' systemd Setup '''
We'll use systemd to control both gunicorn and NetBox's background worker process. First, copy ''' contrib/netbox.service ''' and ''' contrib/netbox-rq.service ''' to the ''' /etc/systemd/system/ '''directory and reload the ''' systemd ''' daemon:
{{{
# sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
# sudo systemctl daemon-reload
}}}
Then, start the ''' netbox ''' and ''' netbox-rq ''' services and enable them to initiate at boot time:
{{{
# sudo systemctl start netbox netbox-rq
# sudo systemctl enable netbox netbox-rq
}}}
You can use the command ''' systemctl ''' status netbox to verify that the WSGI service is running:
{{{
systemctl status netbox.service
}}}

You should see output similar to the following:
{{{
● netbox.service - NetBox WSGI Service
     Loaded: loaded (/etc/systemd/system/netbox.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2021-08-30 04:02:36 UTC; 14h ago
       Docs: https://docs.netbox.dev/
   Main PID: 1140492 (gunicorn)
      Tasks: 19 (limit: 4683)
     Memory: 666.2M
     CGroup: /system.slice/netbox.service
             ├─1140492 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
             ├─1140513 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
             ├─1140514 /opt/netbox/venv/bin/python3 /opt/netbox/venv/bin/gunicorn --pid /va>
...
}}}

Once you've verified that the WSGI workers are up and running, move on to HTTP server setup.