Nautobot Docker Images¶
Nautobot is packaged as a Docker image for use in a production environment; developer images are also provided for those working on App development and testing. The Docker image and deployment strategies are being actively developed, check back here or join the #nautobot channel on Network to Code's Slack community for the most up to date information.
Python Versions¶
Docker images are published for multiple supported Python versions. The default image, recommended for most users, is based on the python:3.12-slim
image.
Changed in version 1.6.1
The Python version for the image tags that do not explicitly state a Python version changed to 3.11 for Nautobot 1.6.1. From now on, these tagged images will always contain the latest supported Python version (e.g., when Python 3.12 support is added, these tags will change to contain Python 3.12). This is a change from Nautobot 1.6.0 and earlier, where tags that did not state a Python version would contain the earliest supported Python version.
Currently images are pushed for the following python versions:
- 3.8
- 3.9
- 3.10
- 3.11
- 3.12
Added in version 1.6.0
Python 3.11 was added to the set of published images.
Removed in version 1.6.0
Python 3.7 was removed from the set of published images as Python 3.7 is now end-of-life.
Added in version 2.3.0
Python 3.12 was added to the set of published images and is now the default version.
Platforms¶
Nautobot docker images are currently provided for both linux/amd64
and linux/arm64
architectures. Please note ARM64 support is untested by our automated tests and should be considered in an alpha state.
Tags¶
Production Tags¶
A set of production-ready Docker images are built for each Nautobot release and published to both Docker Hub and the GitHub Container Registry.
To get a specific tagged image from Docker Hub or the GitHub Container Registry run:
or
The following tags are available on both Docker Hub and the GitHub Container Registry:
Tag | Nautobot Version | Python Version | Example |
---|---|---|---|
latest |
Latest stable release | 3.12 | latest |
latest-py${PYTHON_VER} |
Latest stable release | As specified | latest-py3.8 |
${NAUTOBOT_VER} |
As specified | 3.12 | 2.3.0 |
${NAUTOBOT_VER}-py${PYTHON_VER} |
As specified | As specified | 2.3.0-py3.8 |
${NAUTOBOT_MAJOR_VER}.${NAUTOBOT_MINOR_VER} |
As specified | 3.12 | 2.3 |
${NAUTOBOT_MAJOR_VER}.${NAUTOBOT_MINOR_VER}-py${PYTHON_VER} |
As specified | As specified | 2.3-py3.8 |
stable |
Latest stable release | 3.12 | stable |
stable-py${PYTHON_VER} |
Latest stable release | As specified | stable-py3.8 |
Developer Tags¶
Additionally, GitHub Actions are used to automatically build "developer" images corresponding to each commit to the ltm-1.6
, develop
, and next
branches. These images are named networktocode/nautobot-dev:${TAG}
and ghcr.io/nautobot/nautobot-dev:${TAG}
, and provide the development dependencies needed to build Nautobot; they can be used as a base for development to develop your own Nautobot apps but should NOT be used in production.
In addition to all tags described in the previous section, the following additional tags are available from the GitHub Container Registry, only for the ghcr.io/nautobot/nautobot-dev
images:
Tag | Nautobot Branch | Python Version |
---|---|---|
develop |
develop , the latest commit |
3.12 |
develop-py${PYTHON_VER} |
develop , the latest commit |
As specified |
ltm-1.6 |
ltm-1.6 , the latest commit |
3.11 |
ltm-1.6-py${PYTHON_VER} |
ltm-1.6 , the latest commit |
As specified |
next |
next , the latest commit |
3.12 |
next-py${PYTHON_VER} |
next , the latest commit |
As specified |
Getting Started¶
Nautobot requires a MySQL or PostgreSQL database and Redis instance before it will start. Because of this the quickest and easiest way to get Nautobot running is with Docker Compose, which will install and configure PostgreSQL and Redis containers for you automatically.
Tip
Whether you're using the Docker CLI, Docker Compose, or Kubernetes, in any case you'll want to set up appropriate health checks for your containers.
Configuration¶
Most configuration parameters are available via environment variables which can be passed to the container. If you desire you can inject your own nautobot_config.py
by overriding /opt/nautobot/nautobot_config.py
using docker volumes by adding -v /local/path/to/custom/nautobot_config.py:/opt/nautobot/nautobot_config.py
to your docker run command, for example:
docker run \
-v /local/path/to/custom/nautobot_config.py:/opt/nautobot/nautobot_config.py \
--name nautobot networktocode/nautobot
Or if you are using docker compose:
services:
nautobot:
image: "networktocode/nautobot"
volumes:
- /local/path/to/custom/nautobot_config.py:/opt/nautobot/nautobot_config.py:ro
Docker only configuration¶
The entry point for the Docker container has some additional features that can be configured via additional environment variables. The following are all optional variables:
NAUTOBOT_CREATE_SUPERUSER
¶
Default: unset
Enables creation of a super user specified by NAUTOBOT_SUPERUSER_NAME
, NAUTOBOT_SUPERUSER_EMAIL
, NAUTOBOT_SUPERUSER_PASSWORD
, and NAUTOBOT_SUPERUSER_API_TOKEN
.
NAUTOBOT_DOCKER_SKIP_INIT
¶
Default: unset
When starting, the container attempts to connect to the database and run database migrations and upgrade steps necessary when upgrading versions. In normal operation this is harmless to run on every startup and validates the database is operating correctly. However, in certain circumstances such as database maintenance when the database is in a read-only mode it may make sense to start Nautobot but skip these steps. Setting this variable to true
will start Nautobot without running these initial steps.
Note
Setting this value to anything other than "false" (case-insensitive) will prevent migrations from occurring.
NAUTOBOT_SUPERUSER_API_TOKEN
¶
Default: unset
If NAUTOBOT_CREATE_SUPERUSER
is true, NAUTOBOT_SUPERUSER_API_TOKEN
specifies the API token of the super user to be created; alternatively the /run/secrets/superuser_api_token
file contents are read for the token. Either the variable or the file is required if NAUTOBOT_CREATE_SUPERUSER
is true.
NAUTOBOT_SUPERUSER_EMAIL
¶
Default: admin@example.com
If NAUTOBOT_CREATE_SUPERUSER
is true, NAUTOBOT_SUPERUSER_EMAIL
specifies the email address of the super user to be created.
NAUTOBOT_SUPERUSER_NAME
¶
Default: admin
If NAUTOBOT_CREATE_SUPERUSER
is true, NAUTOBOT_SUPERUSER_NAME
specifies the username of the super user to be created.
NAUTOBOT_SUPERUSER_PASSWORD
¶
Default: unset
If NAUTOBOT_CREATE_SUPERUSER
is true, NAUTOBOT_SUPERUSER_PASSWORD
specifies the password of the super user to be created; alternatively the /run/secrets/superuser_password
file contents are read for the password. Either the variable or the file is required if NAUTOBOT_CREATE_SUPERUSER
is true.
uWSGI¶
The docker container uses uWSGI to serve Nautobot. A default configuration is provided, and can be overridden by injecting a new uwsgi.ini
file at /opt/nautobot/uwsgi.ini
. There are a couple of environment variables provided to override some uWSGI defaults:
NAUTOBOT_UWSGI_BUFFER_SIZE
¶
Added in version 1.3.9
Default: 4096
Max: 65535
The max size of non-body request payload, roughly the size of request headers for uWSGI. Request headers that might contain lengthy query parameters, for example GraphQL or Relationship filtered lookups, might go well over the default limit. Increasing this limit will have an impact on running memory usage. Please see the uWSGI documentation for more information.
This can also be overridden by appending -b DESIRED_BUFFER_SIZE
, ex: -b 8192
, to the entry command in all Nautobot containers running uWSGI if you are on a release before 1.3.9
.
NAUTOBOT_UWSGI_LISTEN
¶
Default: 128
The socket listen queue size of uWSGI. In production environments it is recommended to increase this value to 1024 or higher, however depending on your platform, this may require additional kernel parameter settings, please see the uWSGI documentation for more information.
Please see the official uWSGI documentation on listen
for more information.
NAUTOBOT_UWSGI_PROCESSES
¶
Default: 3
The number of worker processes uWSGI will spawn.
Please see the official uWSGI documentation on processes
for more information.
SSL¶
Self signed SSL certificates are included by default with the container. For a production deployment you should utilize your own signed certificates, these can be injected into the container at runtime using docker volumes. The public certificate should be placed at /opt/nautobot/nautobot.crt
and the private key should be at /opt/nautobot/nautobot.key
. Using a docker run
these can be injected using the -v
parameter:
docker run \
-v /local/path/to/custom/nautobot.crt:/opt/nautobot/nautobot.crt \
-v /local/path/to/custom/nautobot.key:/opt/nautobot/nautobot.key \
--name nautobot networktocode/nautobot
Or if you are using docker-compose
:
services:
nautobot:
image: "networktocode/nautobot"
volumes:
- /local/path/to/custom/nautobot.crt:/opt/nautobot/nautobot.crt:ro
- /local/path/to/custom/nautobot.key:/opt/nautobot/nautobot.key:ro
Nautobot Apps¶
At this time adding Nautobot Apps to the existing Docker image is not supported, however, you can use the Nautobot image as the base within your Dockerfile
to install your own Apps, here is an example dockerfile:
FROM networktocode/nautobot
RUN pip install nautobot-chatops
COPY nautobot_config.py /opt/nautobot/nautobot_config.py
Building the Image¶
If you have a development environment you can use invoke
to build the Docker image. By default invoke build
will build the dev
image:
After some output and a prompt is returned:
Example output:
REPOSITORY TAG IMAGE ID CREATED SIZE
local/nautobot-dev local-py3.8 0d93eec7dfea 5 minutes ago 1.31GB
If you need to build or test the final
image, you must set your invoke.yml
to use docker-compose.final.yml
in place of docker-compose.dev.yml
:
---
nautobot:
compose_files:
- "docker-compose.yml"
- "docker-compose.postgres.yml"
- "docker-compose.final.yml"
Then you can re-run the invoke build
command:
Example output:
Example output:
REPOSITORY TAG IMAGE ID CREATED SIZE
local/nautobot-final local-py3.8 e03e752fcc6b 27 minutes ago 629MB
Similarly, you can use docker-compose.final-dev.yml
if you wish to build and test the final-dev
image.
Docker Compose¶
An example library for using Docker Compose to build out all of the components for Nautobot can be found within the Nautobot community. Please see https://github.com/nautobot/nautobot-docker-compose/ for examples on the base application, LDAP integration, and using Apps.