Getting started
General deployment notes
The application will be by default deployed both on ipam.{{ ansible_domain
}} as well as dcim.{{ ansible_domain }} DNS domains, for convenience.
You should either point these domains to the deployment host via DNS, or change
the netbox__fqdn to set a desired subdomain.
By default NetBox will allow connections only to the specified DNS domains and deny any other domain that might point to the host it's deployed on.
After the database initialization, the role will create an initial superuser
account with random password stored in the DebOps secret/ directory. The
username will be the first admin user defined by the debops.core Ansible
role.
By default anonymous access to NetBox is disabled.
Python virtualenv support
The NetBox application will be deployed in a Python virtualenv
environment to separate it from the system Python installation. By default the
environment will be created and maintained in the /usr/local/lib/netbox/
directory using an unprivileged netbox account.
The NetBox Python requirements will be installed in the requested versions from PyPI; this might take a while.
The role will install additional Python modules, gunicorn and
setproctitle, to support internal application server and/or management by
the system-wide gunicorn service.
Internal application server
The debops.netbox role can deploy NetBox with either a system-wide
gunicorn service (default), or with an internal gunicorn application
sever using its own netbox systemd unit file. The role automatically
detects if the debops.gunicorn role has been deployed on a host and
switches between these modes as needed.
manage.py for NetBox power users
The NetBox goody manage.py is conveniently accessible using a script
that the role installs called netbox-manage. It uses sudo to
switch to the NetBox user, activates the virtualenv and run manage.py.
Call it without parameters to see the available subcommands. The user calling
the script must have privileges to run commands as the NetBox system user.
Example inventory
The NetBox application uses a PostgreSQL database as its backend, therefore you
need to setup a PostgreSQL server which the application can access. To
configure one on the same host as NetBox, add that host to the
[debops_service_postgresql_server] Ansible inventory group. See the
debops.postgresql_server role documentation to see how to use the database
server remotely.
The Redis service is used for caching and is now required by NetBox as well.
The netbox__redis_* variables in the debops.netbox role can be used
to point NetBox to a remote Redis service; by default the role expects Redis to
be installed locally. You can deploy a Redis Server or cluster using the
debops.redis_server (and optionally debops.redis_sentinel)
Ansible roles. See their documentation for more details.
To deploy NetBox on a given host, you need to add that host to the
[debops_service_netbox] Ansible inventory group. Complete, example
inventory:
[debops_all_hosts]
hostname
[debops_service_redis_server]
hostname
[debops_service_postgresql_server]
hostname
[debops_service_netbox]
hostname
Example playbook
If you are using this role without DebOps, here's an example Ansible playbook
that uses the debops.netbox role:
---
- name: Manage NetBox IPAM/DCIM application
collections: [ 'debops.debops', 'debops.roles01',
'debops.roles02', 'debops.roles03' ]
hosts: [ 'debops_service_netbox' ]
become: True
environment: '{{ inventory__environment | d({})
| combine(inventory__group_environment | d({}))
| combine(inventory__host_environment | d({})) }}'
roles:
- role: keyring
tags: [ 'role::keyring', 'skip::keyring',
'role::postgresql', 'role::nginx', 'role::netbox' ]
keyring__dependent_apt_keys:
- '{{ postgresql__keyring__dependent_apt_keys }}'
- '{{ nginx__keyring__dependent_apt_keys }}'
keyring__dependent_gpg_keys:
- '{{ netbox__keyring__dependent_gpg_keys }}'
- role: apt_preferences
tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
apt_preferences__dependent_list:
- '{{ gunicorn__apt_preferences__dependent_list }}'
- '{{ postgresql__apt_preferences__dependent_list }}'
- '{{ nginx__apt_preferences__dependent_list }}'
- role: cron
tags: [ 'role::cron', 'skip::cron' ]
- role: logrotate
tags: [ 'role::logrotate', 'skip::logrotate' ]
logrotate__dependent_config:
- '{{ gunicorn__logrotate__dependent_config }}'
- role: ferm
tags: [ 'role::ferm', 'skip::ferm' ]
ferm__dependent_rules:
- '{{ nginx__ferm__dependent_rules }}'
- role: python
tags: [ 'role::python', 'skip::python', 'role::postgresql', 'role::gunicorn', 'role::netbox' ]
python__dependent_packages3:
- '{{ gunicorn__python__dependent_packages3 }}'
- '{{ ldap__python__dependent_packages3 }}'
- '{{ netbox__python__dependent_packages3 }}'
- '{{ nginx__python__dependent_packages3 }}'
- '{{ postgresql__python__dependent_packages3 }}'
python__dependent_packages2:
- '{{ gunicorn__python__dependent_packages2 }}'
- '{{ ldap__python__dependent_packages2 }}'
- '{{ netbox__python__dependent_packages2 }}'
- '{{ nginx__python__dependent_packages2 }}'
- '{{ postgresql__python__dependent_packages2 }}'
- role: ldap
tags: [ 'role::ldap', 'skip::ldap' ]
ldap__dependent_tasks:
- '{{ netbox__ldap__dependent_tasks }}'
- role: postgresql
tags: [ 'role::postgresql', 'skip::postgresql' ]
postgresql__dependent_roles:
- '{{ netbox__postgresql__dependent_roles }}'
postgresql__dependent_groups:
- '{{ netbox__postgresql__dependent_groups }}'
postgresql__dependent_databases:
- '{{ netbox__postgresql__dependent_databases }}'
postgresql__dependent_pgpass:
- '{{ netbox__postgresql__dependent_pgpass }}'
- role: gunicorn
tags: [ 'role::gunicorn', 'skip::gunicorn' ]
gunicorn__dependent_applications:
- '{{ netbox__gunicorn__dependent_applications }}'
- role: nginx
tags: [ 'role::nginx', 'skip::nginx' ]
nginx__dependent_upstreams:
- '{{ netbox__nginx__dependent_upstreams }}'
nginx__dependent_servers:
- '{{ netbox__nginx__dependent_servers }}'
- role: netbox
tags: [ 'role::netbox', 'skip::netbox' ]