Configuration - Nautobot Documentation

Skip to content

# Nautobot Configuration

This section describes how to get started with configuring Nautobot.

## Initializing the Configuration

An initial configuration can be created by executing `nautobot-server init`. This will generate a new configuration with all of the default settings provided for you, and will also generate a unique `SECRET_KEY`.

By default (if you haven't set `NAUTOBOT_ROOT` to some other value), the file will be created at `$HOME/.nautobot/nautobot_config.py`:

    nautobot-server init

Example output:

    Configuration file created at '/opt/nautobot/nautobot_config.py'

Tip

The Nautobot Installation Docs example sets `NAUTOBOT_ROOT` to `/opt/nautobot`, so `nautobot_config.py` would be found at `/opt/nautobot/nautobot_config.py`.

You may specify a different location for the configuration as the argument to `init`:

    nautobot-server init /tmp/custom_config.py

    Configuration file created at '/tmp/custom_config.py'

Note

Throughout the documentation, the configuration file will be referred to by name as `nautobot_config.py`. If you use a custom file name, you must use that instead.

## Specifying your Configuration

If you place your configuration in the default location at `$HOME/.nautobot/nautobot_config.py`, you may utilize the `nautobot-server` command and it will use that location automatically.

If you do not wish to utilize the default location, you have two options:

### Config argument

You may provide the `--config` argument when executing `nautobot-server` to tell Nautobot where to find your configuration. For example, to start a Nautobot shell with the configuration in an alternate location:

    nautobot-server --config=/etc/nautobot_config.py nbshell

### Environment variable

You may also set the `NAUTOBOT_CONFIG` environment variable to the location of your configuration file so that you don't have to keep providing the `--config` argument. If set, this overrides the default location.

    export NAUTOBOT_CONFIG=/etc/nautobot_config.py
    nautobot-server nbshell

## Nautobot Root Directory

By default, Nautobot will always read or store files in `~/.nautobot` to allow for installation without requiring superuser (root) permissions.

The `NAUTOBOT_ROOT` configuration setting specifies where these files will be stored on your file system. You may customize this location by setting the `NAUTOBOT_ROOT` environment variable. For example:

    export NAUTOBOT_ROOT=/opt/nautobot

This setting is also used in the Nautobot deployment guide to make the `nautobot-server` command easier to find and use.

Note

The `--config` argument and the `NAUTOBOT_CONFIG` environment variable will always take precedence over `NAUTOBOT_ROOT` for the purpose of telling Nautobot where your `nautobot_config.py` can be found.

Warning

Do not override `NAUTOBOT_ROOT` in your `nautobot_config.py`. It will not work as expected. If you need to customize this setting, please always set the `NAUTOBOT_ROOT` environment variable.

## File Storage

Nautobot is capable of storing various types of files. This includes Jobs, Git repositories, image attachments, and static files (CSS, JavaScript, etc.).

Each of the features requiring use of file storage default to being stored in `NAUTOBOT_ROOT`. If desired, you may customize each one individually. Please see each feature's respective documentation linked above for how to do that.

## Configuration Parameters

While Nautobot has many configuration settings, only a few of them must be defined at the time of installation. These configuration parameters may be set in `nautobot_config.py` or by default many of them may also be set by environment variables. Please see the following links for more information:

- Settings
- Optional Authentication Configuration:
  - LDAP Authentication
  - Remote User Authentication
  - SSO Authentication

## Changing the Configuration

Configuration settings may be changed at any time. However, the WSGI service (e.g. uWSGI) must be restarted before the changes will take effect. For example, if you're running Nautobot using `systemd:`

    sudo systemctl restart nautobot nautobot-worker

## Advanced Configuration

### Troubleshooting the Configuration

To facilitate troubleshooting and debugging of settings, try inspecting the settings from a shell.

First get a Nautobot shell, which automatically loads the Django settings:

    nautobot-server nbshell

Output:

    # Shell Plus Model Imports
    ...
    # Shell Plus Django Imports
    ..
    from django.conf import settings
    ...
    # Django version 4.2.15
    # Nautobot version 2.3.3b1
    ...
    Python 3.12.6 (main, Sep 12 2024, 21:12:08) [GCC 12.2.0] on linux
    Type "help", "copyright", "credits" or "license" for more information.
    (InteractiveConsole)
    >>>

Inspect the `SETTINGS_PATH` variable. Does it match the configuration you're expecting to be loading?

    >>> settings.SETTINGS_PATH
    '/home/example/.nautobot/nautobot_config.py'

If not, double check that you haven't set the `NAUTOBOT_CONFIG` environment variable, or if you did, that the path defined there is the correct one.

    echo $NAUTOBOT_CONFIG

### Adding your own dependencies

Warning

Be cautious not to confuse extra applications with Nautobot Apps which are installed using the `PLUGINS` setting. They are similar, but distinctly different!

Nautobot, being a Django application, allows for installation of additional dependencies utilizing the `INSTALLED_APPS` settings. Due to the highly specialized nature of Nautobot, you cannot safely do this.

For example, let's assume that you want to install the popular `django-health-check` application to your Nautobot deployment which requires you to add one or more `health_check` entries to your `INSTALLED_APPS`.

If you attempt to modify `INSTALLED_APPS` yourself, you might see an error such as this:

    Traceback (most recent call last):
      File "/usr/local/bin/nautobot-server", line 8, in <module>
        sys.exit(main())
      File "/usr/local/lib/python3.12/site-packages/nautobot/core/cli.py", line 53, in main
        initializer=_configure_settings,  # Called after defaults
      File "/usr/local/lib/python3.12/site-packages/nautobot/core/runner/runner.py", line 193, in run_app
        management.execute_from_command_line([runner_name, command] + command_args)
      File "/usr/local/lib/python3.12/site-packages/django/core/management/__init__.py", line 401, in execute_from_command_line
        utility.execute()
      File "/usr/local/lib/python3.12/site-packages/django/core/management/__init__.py", line 377, in execute
        django.setup()
      File "/usr/local/lib/python3.12/site-packages/django/__init__.py", line 24, in setup
        apps.populate(settings.INSTALLED_APPS)
      File "/usr/local/lib/python3.12/site-packages/django/apps/registry.py", line 95, in populate
        "duplicates: %s" % app_config.label)
    django.core.exceptions.ImproperlyConfigured: Application labels aren't unique, duplicates: health_check

To make it work, you would simply specify `EXTRA_INSTALLED_APPS` instead:

    EXTRA_INSTALLED_APPS = [
        'health_check',
        ...
    ]

For more information on installing extra applications, please see the documentation on Extra Applications.

For more information on installing or developing Nautobot Apps, please see the documentation on Apps.