Skip to content

Installing Nautobot

This section of the documentation discusses installing and configuring the Nautobot application itself.

These instructions will guide you through the following actions:

  • Establish a Nautobot root directory for the application environment
  • Create a nautobot system account
  • Create a Python virtual environment (virtualenv)
  • Install Nautobot and all required Python packages
  • Run the database schema migrations
  • Aggregate static resource files on disk
  • Verify the installation using the development/test server

Important

Your database server and Redis must have been successfully installed before continuing with deployment steps. If you haven't done that yet, please visit the guide on Installing Nautobot Dependencies

Create the Nautobot System User

Create a system user account named nautobot. This user will own all of the Nautobot files, and the Nautobot web services will be configured to run under this account.

Choosing Nautobot Root

You need to select a directory path where everything related to Nautobot will be installed. We will use this value across the documentation and it will be referred to as NAUTOBOT_ROOT.

We will be using this path as the home directory of the nautobot user.

Tip

We have selected /opt/nautobot, but you may use any directory you choose.

The following command also creates the /opt/nautobot directory and sets it as the home directory for the user.

Add system user
sudo useradd --system --shell /bin/bash --create-home --home-dir /opt/nautobot nautobot

Setup the Virtual Environment

Python Virtual Environment

A Python virtual environment or virtualenv is like a container for a set of Python packages. A virtualenv allows you to build environments suited to specific projects without interfering with system packages or other projects.

When installed per the documentation, Nautobot uses a virtual environment in production.

In the following steps, we will have you create the virtualenv within the NAUTOBOT_ROOT you chose in the previous step. This is the same we had you set as the home directory as the nautobot user.

Note

Instead of deliberately requiring you to activate/deactivate the virtualenv, we are emphasizing on relying on the $PATH to access programs installed within it. We find this to be much more intuitive and natural when working with Nautobot in this way.

Create the Virtual Environment

As root, we're going to create the virtualenv in our NAUTOBOT_ROOT as the nautobot user to populate the /opt/nautobot directory with a self-contained Python environment including a bin directory for scripts and a lib directory for Python libraries.

Create the Virtual Environment
sudo -u nautobot python3 -m venv /opt/nautobot
Create the Virtual Environment
sudo -u nautobot python3.8 -m venv /opt/nautobot

Update the Nautobot .bashrc

So what about the NAUTOBOT_ROOT? We've referenced this environment variable several times. Here is where it finally gets set.

We need to set the NAUTOBOT_ROOT environment variable for the nautobot user and make sure that it always set without having to do it manually.

Run this command to update ~/.bashrc for nautobot so that anytime you become nautobot, your NAUTOBOT_ROOT will be set automatically.

Add NAUTOBOT_ROOT to the nautobot user .bashrc file
echo "export NAUTOBOT_ROOT=/opt/nautobot" | sudo tee -a ~nautobot/.bashrc
Example bashrc update output
Example output of updating bashrc
export NAUTOBOT_ROOT=/opt/nautobot

Sudo to nautobot

It is critical to install Nautobot as the nautobot user so that we don't have to worry about fixing permissions later.

Log into the nautobot user
sudo -iu nautobot
Validate the NAUTOBOT_ROOT variable

Observe also that you can now echo the value of the NAUTOBOT_ROOT environment variable that is automatically set because we added to .bashrc:

Verify Nautobot Root
echo $NAUTOBOT_ROOT
Example NAUTOBOT_ROOT output 
/opt/nautobot

Warning

Unless explicitly stated, all remaining steps requiring the use of pip3 or nautobot-server in this document should be performed as the nautobot user!

Prepare the Virtual Environment

Understanding the Virtual Environment

Because the nautobot user was created with NAUTOBOT_ROOT set as its home directory and we had you set the shell to /bin/bash, the binary path $NAUTOBOT_ROOT/bin is automatically added to the beginning of the $PATH environment variable:

Print out the PATH variable
echo $PATH
Example path output
Example output of a PATH variable
/opt/nautobot/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin
Print out the PATH variable
echo $PATH
Example path output
Example output of a PATH variable
/opt/nautobot/.local/bin:/opt/nautobot/bin:/opt/nautobot/.local/bin:/opt/nautobot/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin

Therefore, any commands executed by the nautobot user will always check $NAUTOBOT_ROOT/bin first.

Since NAUTOBOT_ROOT also contains the Python virtualenv for Nautobot, all of the commands you will execute as the nautobot user, will automatically prefer the virtualenv's commands because they come first in the $PATH.

As the nautobot user, you may use which pip3 to confirm that you are using the correct version of pip3. The path should match that of $NAUTOBOT_ROOT/bin. For example:

Print out location of the pip3 executable
which pip3
Example which pip3 output
Example output
/opt/nautobot/bin/pip3

This makes sure that the version of Python you're using, as well any dependencies that you install, remain isolated in this environment.

Before we install anything into the virtualenv, we want to make sure that Pip is running the latest version.

Pip is Python's package installer and is referred interchangeably as pip or pip3. For the purpose of this document, we'll deliberately be referring to it as pip3. Many common issues can be solved by running the latest version of Pip. Before continuing with installing Nautobot, upgrade Pip to its latest release.

We also want to deliberately install the wheel library which will tell Pip to always try to install wheel packages if they are available. A wheel is a pre-compiled Python package, which is quicker and safer to install because it does not require development libraries or gcc to be installed on your system just so that some more advanced Python libraries can be compiled.

Update Python Pip and Wheel
pip3 install --upgrade pip wheel
Example pip update output 
Requirement already satisfied: pip in ./lib/python3.10/site-packages (22.0.2)
Collecting pip
Downloading pip-24.0-py3-none-any.whl (2.1 MB)
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2.1/2.1 MB 14.8 MB/s eta 0:00:00
Collecting wheel
Downloading wheel-0.43.0-py3-none-any.whl (65 kB)
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 65.8/65.8 KB 11.8 MB/s eta 0:00:00
Installing collected packages: wheel, pip
Attempting uninstall: pip
    Found existing installation: pip 22.0.2
    Uninstalling pip-22.0.2:
    Successfully uninstalled pip-22.0.2
Successfully installed pip-24.0 wheel-0.43.0

By default, Pip will now install Python packages as wheels. In most cases this is desirable, however in some cases the wheel versions of packages may have been compiled with options differing from what is needed for a specific scenario. One such case presents itself here - the wheel for pyuwsgi, a key web server component of Nautobot, is built without SSL (HTTPS) support. This may be fine for a non-production deployment of Nautobot, such as in your lab, but for production deployments, not supporting HTTPS will not do at all. Fortunately, you can tell Pip when you don't want to use wheels for a specific package by passing the --no-binary=<package> CLI parameter. We'll use that below.

Great! We have NAUTOBOT_ROOT ready for use by the nautobot user, so let's proceed to verifying the installation.

Install Nautobot

Use Pip to install Nautobot:

Pip install Nautobot
pip3 install --no-binary=pyuwsgi nautobot

Use Pip to install Nautobot with the MySQL client:

Pip install Nautobot
pip3 install --no-binary=pyuwsgi "nautobot[mysql]"

Verify your Nautobot Installation

You should now have a fancy nautobot-server command in your environment. This will be your gateway to all things Nautobot! Run it to confirm the installed version of nautobot:

Verify Nautobot install
nautobot-server --version

Configuration

Before you can use Nautobot, you'll need to configure it by telling it where your database and Redis servers can be found, among other things. This is done with the nautobot_config.py configuration file.

Initialize your configuration

Initialize a new configuration by running nautobot-server init. You may specify an alternate location and detailed instructions for this are covered in the documentation on Nautobot Configuration.

However, because we've set the NAUTOBOT_ROOT, this command will automatically create a new nautobot_config.py at the default location based on this at $NAUTOBOT_ROOT/nautobot_config.py:

Initialize Nautobot server
nautobot-server init
Example nautobot-server init output
Example `nautobot-server init`
Nautobot would like to send anonymized installation metrics to the project's maintainers.
These metrics include the installed Nautobot version, the Python version in use, an anonymous "deployment ID", and a list of one-way-hashed names of enabled Nautobot Apps and their versions.
Allow Nautobot to send these metrics? [y/n]:
Example with Metrics sent
Installation metrics will be sent when running 'nautobot-server post_upgrade'. Thank you!
Configuration file created at /opt/nautobot/nautobot_config.py
Added in version 1.6.0

The nautobot-server init command will now prompt you to set the initial value for the INSTALLATION_METRICS_ENABLED setting. See the send_installation_metrics command for more information about the feature that this setting toggles.

Required Settings

Your nautobot_config.py provides sane defaults for all of the configuration settings. You will inevitably need to update the settings for your environment, most notably the DATABASES setting. If you do not wish to modify the config, by default, many of these configuration settings can also be specified by environment variables. Please see Required Settings for further details.

Edit $NAUTOBOT_ROOT/nautobot_config.py, and head over to the documentation on Required Settings to tweak your required settings. At a minimum, you'll need to update the following settings:

  • ALLOWED_HOSTS: You must set this value. This can be set to ["*"] for a quick start, but this value is not suitable for production deployment.
  • DATABASES: Database connection parameters, see below.
  • Redis settings: Redis configuration requires multiple settings, if different from the defaults. If you installed Redis on the same system as Nautobot, you most likely do not need to change these settings.
  • At a minimum, you'll need to update the "USER" and "PASSWORD" fields under DATABASES.
  • At a minimum, you'll need to update the "USER" and "PASSWORD" fields under DATABASES.
  • Additionally, since Nautobot's configuration defaults to assuming PostgreSQL, you must change the "ENGINE" setting from django.db.backends.postgresql to django.db.backends.mysql.
  • If you want to enable support for Unicode text, including emojis, please make sure to add "OPTIONS": {"charset": "utf8mb4"}. Refer to the configuration guide on MySQL Unicode settings for more information.

Warning

You absolutely must update your required settings in your nautobot_config.py or Nautobot will not work.

Save your changes to your nautobot_config.py and then proceed to the next step.

Optional Settings

All Python packages required by Nautobot will be installed automatically when running pip3 install nautobot.

Nautobot also supports the ability to install optional Python packages. If desired, these packages should be listed in local_requirements.txt within the NAUTOBOT_ROOT directory, such as /opt/nautobot/local_requirements.txt.

If you decide to use any Nautobot Apps, they should be listed in the file.

Examples of local_requirements.txt

We will cover two examples of common optional settings below.

NAPALM

Nautobot provides built-in support for the NAPALM automation library, which allows Nautobot to fetch live data from devices and return it to a requester via its REST API. The NAPALM_USERNAME and NAPALM_PASSWORD configuration parameters define the credentials to be used when connecting to a device.

To use NAPALM, add nautobot[napalm] to your local_requirements.txt so that it can be installed and kept up to date:

Add napalm to the local_requirements.txt file
echo "nautobot[napalm]" >> $NAUTOBOT_ROOT/local_requirements.txt

Remote File Storage

By default, Nautobot will use the local filesystem to store uploaded files. To use a remote filesystem, install the django-storages library and configure your desired storage backend in nautobot_config.py.

To use remote file storage, add nautobot[remote_storage] to your local_requirements.txt so that it can be installed and kept up to date:

Add remote storage to local_requirements.txt
echo "nautobot[remote_storage]" >> $NAUTOBOT_ROOT/local_requirements.txt

For an example of using django-storages with AWS S3 buckets, visit the django-storages with S3 user-guide.

Prepare the Database

Before Nautobot can run, the database migrations must be performed to prepare the database for use. This will populate the database tables and relationships:

Push migrations onto the Nautobot database
nautobot-server migrate

Create a Superuser

Nautobot does not come with any predefined user accounts. You'll need to create a administrative superuser account to be able to log into Nautobot for the first time. Specifying an email address for the user is not required, but be sure to use a very strong password.

Create Nautobot local super user account
nautobot-server createsuperuser
Example with admin user created
Example output with admin user created
Username: admin
Email address:
Password:
Password (again):
Superuser created successfully.

Create Static Directories

Nautobot relies upon many static files including:

Each of these have their own corresponding setting that defined in nautobot_config.py, but by default they will all be placed in NAUTOBOT_ROOT unless you tell Nautobot otherwise by customizing their unique variable.

The collectstatic command will create these directories if they do not exist, and in the case of the static files directory, it will also copy the appropriate files:

Collect static files
nautobot-server collectstatic
Collect static example output
Collect static output
1103 static files copied to '/opt/nautobot/static'.

Install Local Requirements

Note

If you did not create a local_requirements.txt above, please skip this step.

This step is entirely optional. As indicated above, we mentioned that any extra local requirements should go into $NAUTOBOT_ROOT/local_requirements.txt.

Install local requirements
pip3 install -r $NAUTOBOT_ROOT/local_requirements.txt

Check your Configuration

Nautobot leverages Django's built-in system check framework to validate the configuration to detect common problems and to provide hints for how to fix them.

Checks are ran automatically when running a development server using nautobot-server runserver, but not when running in production using WSGI.

Hint

Get into the habit of running checks before deployments!

Run a nautobot-server check
nautobot-server check
nautobot-server check output
Example nautobot-server check output
System check identified no issues (0 silenced).

Test the Application

At this point, we should be able to run Nautobot's development server for testing. We can check by starting a development instance:

Optional: Test the Nautobot application
nautobot-server runserver 0.0.0.0:8080 --insecure

Next, connect to the name or IP of the server (as defined in ALLOWED_HOSTS) on port 8080; for example, http://127.0.0.1:8080/. You should be greeted with the Nautobot home page.

Danger

DO NOT USE THIS SERVER IN A PRODUCTION SETTING. The development server is for development and testing purposes only. It is neither performant nor secure enough for production use.

Warning

If the test service does not run, or you cannot reach the Nautobot home page, something has gone wrong. Do not proceed with the rest of this guide until the installation has been corrected. Some platforms (such as CentOS) have a firewall enabled by default. If you are unable to connect to the server url on port 8080, verify the firewall policy to allow the appropriate connections, or select an already permitted port.

Important

Certain Nautobot features (Git repository synchronization, webhooks, jobs, etc.) depend on the presence of Nautobot's background Celery worker process, which is not automatically started by the runserver command. To start it for testing purposes, you can run nautobot-server celery worker separately. For production use, Nautobot and the worker processes should be managed by systemd rather than started manually, as described in the next section of this documentation.

Screenshot Examples

Unauthenticated users will be presented with a login page:

Nautobot UI as seen by a non-authenticated user

Try logging in using the superuser account we just created. Once authenticated, you'll be able to access all areas of the UI:

Nautobot UI as seen by an administrator

Type Ctrl-C to stop the development server. Now you're ready to proceed to starting Nautobot as a system service.