Netbox Docker

Ansible role to configure NetBox as a docker-compose project.

This repository started as a fork of wastrachan/ansible-role-netbox-docker but due to substantial changes and enhancements introduced over time, this fork has somewhat diverged from the upstream project. While we acknowledge the original work as our foundation, users should be aware that the functionality, structure, license and features of this fork may differ considerably from the original repository. We recommend reviewing the commit history and documentation within this fork to understand the current state and capabilities of this Ansible role.

Compatibility

Operating Systems

This role is compatible with the following linux distributions:

• Ubuntu
• Debian
• Red Hat Entreprise Linux (RHEL)
• Fedora

Netbox

This role is compatible with the following versions of Netbox-Docker and should follow the same compatibility matrix as the upstream project for the most part:

• 3.0.2 (NetBox v4.1.x and above. See NetBox Releases)
• 2.9.1 (NetBox v4.0.x. See NetBox Releases)]

Installation

Ansible Galaxy

Install this role with Ansible Galaxy:

ansible-galaxy install git+https://github.com/jsenecal/ansible-role-netbox-docker.git

Local Installation

If you'd like to include this role directly in a playbook, set your roles_path to ./roles via environment variable or ansible.cfg.

Then, add this role to your playbook's requirements.yml:

- src: https://github.com/jsenecal/ansible-role-netbox-docker
  version: master
  name: netbox-docker

And finally, install the role with Ansible Galaxy:

ansible-galaxy install -r requirements.yml

Requirements

docker and docker-compose must be available and installed on the target system.

Role Variables

Configuration and installation options are made available as variables. Some of these (secret_key and passwords) should be overridden before use!

Option	Default	Description
netbox_base_path	/opt/netbox	Root path for netbox's docker-compose file and data store
netbox_port	8080	Host port to expose netbox on. If blank, netbox's port is not exposed
netbox_netbox_image	docker.io/netboxcommunity/netbox:v4.1-3.0.1	Netbox docker image tag
netbox_valkey_image	docker.io/valkey/valkey:8.0-alpine	Valkey docker image tag
netbox_postgres_image	docker.io/postgres:16-alpine	Postgres docker image tag
netbox_caddy_image	docker.io/caddy:2-alpine	Caddy docker image tag
netbox_admin_api_token	-	API token for the default admin user, created on first run
netbox_admin_email	[email protected]	Email of the default admin user, created on first run
netbox_admin_password	admin	Password for the default admin user, created on first run
netbox_admin_username	admin	Username of the default admin user, created on first run
netbox_allowed_hosts	*	If set, connections will be restricted to this list host names (also used in caddy)
netbox_cors_origin_allow_all	true	If set to true, all CORS origins will be allowed
netbox_cors_origin_whitelist	http://localhost	Whitelist of acceptable CORS origin headers
netbox_default_page_size	250	Default number of objects for paginated views
netbox_email_certfile	-	Email server settings documentation
netbox_email_from	[email protected]	Email server settings documentation
netbox_email_keyfile	-	Email server settings documentation
netbox_email_password	-	Email server settings documentation
netbox_email_port	25	Email server settings documentation
netbox_email_server	localhost	Email server settings documentation
netbox_email_timeout	5	Email server settings documentation
netbox_email_use_ssl	false	Email server settings documentation
netbox_email_use_tls	false	Email server settings documentation
netbox_email_username	netbox	Email server settings documentation
netbox_enforce_global_unique	false	Enforcement of unique IP space can be toggled on a per-VRF basis. To enforce unique IP space within the global table, set this to true
netbox_graphql_enabled	true	Enable GraphQL API
netbox_housekeeping_interval	86400	Interval to run housekeeping worker
netbox_container_labels	[]	Optional extra container labels to apply to the netbox container. See Traefiknginx-proxy Support
netbox_container_env	[]	Optional extra container environment variables to apply to the netbox container. See Traefik/nginx-proxy Support
netbox_login_required	false	Whether or not a user must be authenticated to view DCIM details in Netbox
netbox_max_page_size	1000	Maximum number of objects for paginated API requests
netbox_metrics_enabled	false	Expose Prometheus monitoring metrics at the HTTP endpoint '/metrics'
netbox_pg_db	netbox	Postgres database name
netbox_pg_host	postgres	Postgres database host. This should not be changed if using the default docker-compose setup.
netbox_pg_password	RANDOM_SEED	Postgres password
netbox_pg_user	netbox	Postgres user
netbox_additional_network_names	-	Extra external networks to attach to the netbox container. See Traefik/nginx-proxy Support
netbox_valkey_cache_host	valkey-cache	Valkey cache instance host. This should not be changed if using the default docker-compose setup.
netbox_valkey_cache_insecure_skip_tls_verify	false	If true, certificates for valkey cache are not checked
netbox_valkey_cache_password	RANDOM_SEED	Valkey cache instance password
netbox_valkey_cache_ssl	false	If true, communication with valkey is secured with SSL
netbox_valkey_host	valkey	Valkey instance host. This should not be changed if using the default docker-compose setup.
netbox_valkey_insecure_skip_tls_verify	false	If true, certificates for valkey are not checked
netbox_valkey_password	RANDOM_SEED	Valkey instance password
netbox_secret_key	RANDOM_SEED	Netbox secret key. Should be at least 50 characters long
netbox_skip_startup_scripts	false	If true, do not run startup scripts on container start
netbox_skip_superuser	false	If true, do not create superuser on container start
netbox_webhooks_enabled	true	If true, enable netbox webhooks functionality
netbox_use_caddy	false	If set, Caddy will be used to serve Netbox over TLS
netbox_caddy_letsencrypt_email	-	Email address to use for letsencrypt automatic certificate generation
netbox_caddy_http_port	80	Caddy HTTP port
netbox_caddy_https_port	443	Caddy HTTPS port
netbox_ssl_cert_bundle	-	Caddy certificate bundle
netbox_ssl_cert_key	-	Caddy certificate key
netbox_extra_config	-	If provided, this string will be rendered as is in config/extra.py
netbox_extra_services	-	Additional services to include in the docker-compose file
netbox_extra_volumes	-	Additional volumes for the nebox container to include in the docker-compose file

Some additional variables are available for advanced configuration. Please refer to the defaults/main.yml file for a complete list.

Plugins

Some variables are available to configure plugins. These are not enabled by default. To enable a plugin, set the netbox_plugins variable to a list of plugins to install. Each plugin should be a dictionary with the following keys:

• name: The name of the plugin to install, as it appears on PyPi, or the name of the directory in the case of a plugin installed from source
• src: The source of the plugin. This can be a URL to a git repository or a local path. If not provided, the plugin will be installed from PyPi
• version: When a src is defined, this defines a valid reference within the plugin's git repository to install or package version. If not provided, HEAD of the default repository branch will be installed or the latest pypi package version if src isnt defined.

For example, to install the netbox-acls plugin from source, you would add the following to your playbook:

netbox_plugins:
  - name: netbox-acls
    src: https://github.com/netbox-community/netbox-acls.git
    version: 1.6.1

Plugin Configuration

netbox_plugins_config is a dictionary of plugin configurations. Each key should be the name of a plugin, and the value should be a dictionary of configuration options for that plugin. Please refer to the plugin's documentation for available configuration options.

Example Playbook

Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:

    - hosts: servers
      roles:
        - netbox-docker

TLS for localhost

Developing locally and testing TLS (i.e. https) features often poses a challenge. This guide is intended for people developing with, on or for NetBox or NetBox Docker on their computer. It allows to access NetBox Docker through TLS on https://localhost:443, https://127.0.0.1:443 and https://[::1]:443. It is based on the setup recommended by the Netbox-Docker wiki on TLS. First install mkcert on your computer. It creates and installs a local CA-Certificate, which will be used by mkcert to create and sign other certificates. This way, your certificates are trusted on your own computer and you don't get a TLS warning in your tools (browsers, cURL, and so forth).

Begin by creating the certificates for localhost and it's IPv4 and IPv6 addresses using the following commands.

mkcert -install
mkcert localhost 127.0.0.1 ::1

This should have created a file called localhost+2.pem and another file called localhost+2-key.pem. Use these two certificates with a slight modification of the setup proposed above:

    - hosts: localhost
      vars:
        netbox_port: null
        netbox_use_caddy: true
        netbox_ssl_cert_bundle: path_to/localhost+2.pem
        netbox_ssl_cert_key: path_to/localhost+2-key.pem
      roles:
        - netbox-docker

Traefik/nginx-proxy Support

This playbook can be used with traefik or jwilder's nginx-proxy by adding labels with netbox_container_labels, or environment variables with netbox_container_env, respectively. Additionally, netbox_additional_network_names will attach the netbox service to additional networks, as traefik/nginx-proxy usually reside in a network other than that created by docker-compose projects. While not a complete guide to these services, your configuration may look like the below:

traefik

netbox_port: null
netbox_additional_network_names: 
  - traefik
netbox_container_labels:
  traefik.enable: "true"
  traefik.http.services.netbox.loadbalancer.server.port: "8080"
  traefik.http.routers.netbox.rule: "Host(`netbox.domain.com`)"

nginx-proxy

netbox_port: null
netbox_additional_network_names: 
  - nginx
netbox_container_env:
  VIRTUAL_HOST: netbox.domain.com
  VIRTUAL_PORT: "8080"

License

This project itself is licensed under the terms of the MIT License.