2017-04-19 16:48:21 +02:00
# netbox-docker
2017-12-13 15:50:30 +01:00
[![Build Status ](https://travis-ci.org/ninech/netbox-docker.svg?branch=master )][travis]
2017-09-29 11:07:52 +02:00
2018-03-08 09:52:35 +01:00
This repository houses the components needed to build NetBox as a Docker container.
2017-12-13 15:50:30 +01:00
Images built using this code are released to [Docker Hub][netbox-dockerhub] every night.
[travis]: https://travis-ci.org/ninech/netbox-docker
[netbox-dockerhub]: https://hub.docker.com/r/ninech/netbox/tags/
2017-04-19 16:48:21 +02:00
## Quickstart
2018-03-08 09:52:35 +01:00
To get NetBox up and running:
2017-04-19 16:48:21 +02:00
```
2017-09-11 15:40:11 +02:00
$ git clone -b master https://github.com/ninech/netbox-docker.git
2017-09-11 15:30:52 +02:00
$ cd netbox-docker
2017-11-29 15:13:55 +01:00
$ docker-compose pull
2017-09-11 15:30:52 +02:00
$ docker-compose up -d
2017-04-19 16:48:21 +02:00
```
2017-09-11 15:30:52 +02:00
The application will be available after a few minutes.
2017-12-26 23:03:02 +01:00
Use `docker-compose port nginx 8080` to find out where to connect to.
2017-09-11 15:30:52 +02:00
```
2017-12-26 23:03:02 +01:00
$ echo "http://$(docker-compose port nginx 8080)/"
2017-09-11 15:30:52 +02:00
http://0.0.0.0:32768/
# Open netbox in your default browser on macOS:
2017-12-26 23:03:02 +01:00
$ open "http://$(docker-compose port nginx 8080)/"
2017-09-11 15:30:52 +02:00
# Open netbox in your default browser on (most) linuxes:
2017-12-26 23:03:02 +01:00
$ xdg-open "http://$(docker-compose port nginx 8080)/" & >/dev/null &
2017-09-11 15:30:52 +02:00
```
2017-04-19 16:48:21 +02:00
2018-03-08 09:52:35 +01:00
Alternatively, use something like [Reception][docker-reception] to connect to _docker-compose_ projects.
2017-11-29 15:13:55 +01:00
2017-04-19 16:48:21 +02:00
Default credentials:
* Username: **admin**
* Password: **admin**
2017-11-29 15:13:55 +01:00
* API Token: **0123456789abcdef0123456789abcdef01234567**
2017-04-19 16:48:21 +02:00
2017-12-13 15:50:30 +01:00
[docker-reception]: https://github.com/ninech/reception
2017-10-16 13:09:17 +02:00
## Dependencies
2017-10-16 13:13:12 +02:00
This project relies only on *Docker* and *docker-compose* meeting this requirements:
2017-10-16 13:09:17 +02:00
* The *Docker version* must be at least `1.13.0` .
* The *docker-compose version* must be at least `1.10.0` .
To ensure this, compare the output of `docker --version` and `docker-compose --version` with the requirements above.
2017-04-19 16:48:21 +02:00
## Configuration
2017-09-11 15:30:52 +02:00
You can configure the app using environment variables. These are defined in `netbox.env` .
2017-12-13 15:50:30 +01:00
Read [Environment Variables in Compose][compose-env] to understand about the various possibilities to overwrite these variables.
(The easiest solution being simply adjusting that file.)
To find all possible variables, have a look at the [configuration.docker.py][docker-config] and [docker-entrypoint.sh][entrypoint] files.
2018-03-08 09:52:35 +01:00
Generally, the environment variables are called the same as their respective NetBox configuration variables.
2017-12-13 15:50:30 +01:00
Variables which are arrays are usually composed by putting all the values into the same environment variables with the values separated by a whitespace ("` `").
2018-03-08 09:52:35 +01:00
For example defining `ALLOWED_HOSTS=localhost ::1 127.0.0.1` would allows access to NetBox through `http://localhost:8080` , `http://[::1]:8080` and `http://127.0.0.1:8080` .
2017-12-13 15:50:30 +01:00
[compose-env]: https://docs.docker.com/compose/environment-variables/
2018-03-08 09:54:06 +01:00
### Production
The default settings are optimized for (local) development environments.
You should therefore adjust the configuration for production setups, at least the following variables:
* `ALLOWED_HOSTS` : Add all URLs that lead to your NetBox instance.
* `DB_*` : Use a persistent database.
* `EMAIL_*` : Use your own mailserver.
* `MAX_PAGE_SIZE` : Use the recommended default of 1000.
* `SUPERUSER_*` : Only define those variables during the initial setup, and drop them once the DB is set up.
### Running on Docker Swarm / Kubernetes / OpenShift
You may run this image in a cluster such as Docker Swarm, Kubernetes or OpenShift, but this is advanced level.
2018-04-03 09:02:19 +02:00
In this case, we encourage you to statically configure NetBox by starting from [NetBox's example config file][default-config], and mounting it into your container in the directory `/etc/netbox/config/` using the mechanism provided by your container platform (i.e. [Docker Swarm configs][swarm-config], [Kubernetes ConfigMap][k8s-config], [OpenShift ConfigMaps][openshift-config]).
2018-03-08 09:54:06 +01:00
But if you rather continue to configure your application through environment variables, you may continue to use [the built-in configuration file][docker-config].
We discourage storing secrets in environment variables, as environment variable are passed on to all sub-processes and may leak easily into other systems, e.g. error collecting tools that often collect all environment variables whenever an error occurs.
Therefore we *strongly advise* to make use of the secrets mechanism provided by your container platform (i.e. [Docker Swarm secrets][swarm-secrets], [Kubernetes secrets][k8s-secrets], [OpenShift secrets][openshift-secrets]).
[The configuration file][docker-config] and [the entrypoint script][entrypoint] try to load the following secrets from the respective files.
If a secret is defined by an environment variable and in the respective file at the same time, then the value from the environment variable is used.
* `SUPERUSER_PASSWORD` : `/run/secrets/superuser_password`
* `SUPERUSER_API_TOKEN` : `/run/secrets/superuser_api_token`
* `DB_PASSWORD` : `/run/secrets/db_password`
* `SECRET_KEY` : `/run/secrets/secret_key`
* `EMAIL_PASSWORD` : `/run/secrets/email_password`
* `NAPALM_PASSWORD` : `/run/secrets/napalm_password`
Please also consider [the advice about running NetBox in production ](#production ) above!
[docker-config]: https://github.com/ninech/netbox-docker/blob/master/docker/configuration.docker.py
[default-config]: https://github.com/digitalocean/netbox/blob/develop/netbox/netbox/configuration.example.py
[entrypoint]: https://github.com/ninech/netbox-docker/blob/master/docker/docker-entrypoint.sh
[swarm-config]: https://docs.docker.com/engine/swarm/configs/
[swarm-secrets]: https://docs.docker.com/engine/swarm/secrets/
[openshift-config]: https://docs.openshift.org/latest/dev_guide/configmaps.html
[openshift-secrets]: https://docs.openshift.org/latest/dev_guide/secrets.html
[k8s-secrets]: https://kubernetes.io/docs/concepts/configuration/secret/
[k8s-config]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/
2018-04-11 22:43:23 +02:00
#### Example Kubernetes Deployment
Check out the project:
```
git clone https://github.com/ninech/netbox-docker.git
cd netbox-docker/kubernetes
```
Fill in the configuration parameters:
* In `netbox.yaml` ,
* Set environment variables in the `netbox-netbox-env` ConfigMap and the `netbox-netbox-secrets` Secret. Secrets must be base64 encoded first (see the inline comments).
* Change the `DB_HOST` environment parameter to be the DNS name (from inside the cluster) for the postgres db. This probably just involves adding the namespace.
* Set the `storageClassName` if required in your cluster.
* In `postgres,yaml` , set the `POSTGRES_PASSWORD` to match `netbox.yaml` .
Deploy to kubernetes:
```
kubectl apply -f .
```
2018-03-08 09:55:56 +01:00
### NAPALM Configuration
Since v2.1.0 NAPALM has been tightly integrated into NetBox.
NAPALM allows NetBox to fetch live data from devices and return it to a requester via its REST API.
To learn more about what NAPALM is and how it works, please see the documentation from the [libary itself][napalm-doc] or the documentation from [NetBox][netbox-napalm-doc] on how it is integrated.
To enable this functionality, simply complete the following lines in `netbox.env` (or appropriate secrets mechanism) :
* `NAPALM_USERNAME` : A common username that can be utilized for connecting to network devices in your environment.
* `NAPALM_PASSWORD` : The password to use in combintation with the username to connect to network devices.
* `NAPALM_TIMEOUT` : A value to use for when an attempt to connect to a device will timeout if no response has been recieved.
However, if you don't need this functionality, leave these blank.
[napalm-doc]: http://napalm.readthedocs.io/en/latest/index.html
[netbox-napalm-doc]: https://netbox.readthedocs.io/en/latest/configuration/optional-settings/#napalm_username
2018-02-16 10:25:26 +01:00
### Custom Initialization Code (e.g. Automatically Setting Up Custom Fields)
2018-01-24 09:21:55 +01:00
2018-02-16 10:25:26 +01:00
When using `docker-compose` , all the python scripts present in `/opt/netbox/startup_scripts` will automatically be executed after the application boots in the context of `./manage.py` .
2018-01-24 09:21:55 +01:00
2018-03-08 09:52:35 +01:00
That mechanism can be used for many things, e.g. to create NetBox custom fields:
2018-01-24 09:21:55 +01:00
```python
# docker/startup_scripts/load_custom_fields.py
from django.contrib.contenttypes.models import ContentType
from extras.models import CF_TYPE_TEXT, CustomField
from dcim.models import Device
from dcim.models import DeviceType
device = ContentType.objects.get_for_model(Device)
device_type = ContentType.objects.get_for_model(DeviceType)
my_custom_field, created = CustomField.objects.get_or_create(
type=CF_TYPE_TEXT,
name='my_custom_field',
description='My own custom field'
)
if created:
my_custom_field.obj_type.add(device)
my_custom_field.obj_type.add(device_type)
```
2018-02-16 10:25:26 +01:00
#### Initializers
2018-03-08 09:52:35 +01:00
Initializers are built-in startup scripts for defining NetBox custom fields, groups and users.
2018-02-16 10:25:26 +01:00
All you need to do is to mount you own `initializers` folder ([see `docker-compose.yml` ][netbox-docker-compose]).
Look at the [`initializers` folder][netbox-docker-initializers] to learn how the files must look like.
Here's an example for defining a custom field:
```yaml
# initializers/custom_fields.yml
text_field:
type: text
label: Custom Text
description: Enter text in a text field.
required: false
filterable: true
weight: 0
on_objects:
- dcim.models.Device
- dcim.models.Rack
- ipam.models.IPAddress
- ipam.models.Prefix
- tenancy.models.Tenant
- virtualization.models.VirtualMachine
```
[netbox-docker-initializers]: https://github.com/ninech/netbox-docker/tree/master/initializers
[netbox-docker-compose]: https://github.com/ninech/netbox-docker/blob/master/docker-compose.yml
#### Custom Docker Image
2018-03-08 09:52:35 +01:00
You can also build your own NetBox Docker image containing your own startup scripts, custom fields, users and groups
2018-02-16 10:25:26 +01:00
like this:
```
ARG VERSION=latest
FROM ninech/netbox:$VERSION
COPY startup_scripts/ /opt/netbox/startup_scripts/
COPY initializers/ /opt/netbox/initializers/
```
2017-12-13 15:50:30 +01:00
2018-04-04 09:50:17 +02:00
## Netbox Version
2017-10-16 13:33:12 +02:00
2018-03-08 09:52:35 +01:00
The `docker-compose.yml` file is prepared to run a specific version of NetBox.
2017-10-16 13:33:12 +02:00
To use this feature, set the environment-variable `VERSION` before launching `docker-compose` , as shown below.
`VERSION` may be set to the name of
2017-12-13 15:50:30 +01:00
[any tag of the `ninech/netbox` Docker image on Docker Hub][netbox-dockerhub].
2017-10-16 13:33:12 +02:00
```
2017-11-29 15:13:55 +01:00
$ export VERSION=v2.2.6
2017-10-16 13:33:12 +02:00
$ docker-compose pull netbox
$ docker-compose up -d
```
2018-03-08 09:52:35 +01:00
You can also build a specific version of the NetBox image. This time, `VERSION` indicates any valid
2017-12-13 15:50:30 +01:00
[Git Reference][git-ref] declared on [the 'digitalocean/netbox' Github repository][netbox-github].
Most commonly you will specify a tag or branch name.
2017-10-16 13:33:12 +02:00
```
$ export VERSION=develop
$ docker-compose build --no-cache netbox
$ docker-compose up -d
```
Hint: If you're building a specific version by tag name, the `--no-cache` argument is not strictly necessary.
This can increase the build speed if you're just adjusting the config, for example.
2017-12-13 15:50:30 +01:00
[git-ref]: https://git-scm.com/book/en/v2/Git-Internals-Git-References
[netbox-github]: https://github.com/digitalocean/netbox/releases
2018-03-08 09:54:34 +01:00
### LDAP enabled variant
The images tagged with "-ldap" contain anything necessary to authenticate against an LDAP or Active Directory server.
The default configuration `ldap_config.py` is prepared for use with an Active Directory server.
Custom values can be injected using environment variables, similar to the main configuration mechanisms.
2017-12-13 15:50:30 +01:00
## Troubleshooting
This section is a collection of some common issues and how to resolve them.
If your issue is not here, look through [the existing issues][issues] and eventually create a new issue.
[issues]: (https://github.com/ninech/netbox-docker/issues)
### Docker Compose basics
* You can see all running containers belonging to this project using `docker-compose ps` .
* You can see the logs by running `docker-compose logs -f` .
Running `docker-compose logs -f netbox` will just show the logs for netbox.
* You can stop everything using `docker-compose stop` .
* You can clean up everything using `docker-compose down -v --remove-orphans` . **This will also remove any related data.**
2018-03-08 09:52:35 +01:00
* You can enter the shell of the running NetBox container using `docker-compose exec netbox /bin/bash` . Now you have access to `./manage.py` , e.g. to reset a password.
2017-12-13 15:50:30 +01:00
* To access the database run `docker-compose exec postgres sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'`
2018-01-15 11:24:48 +01:00
* To create a database backup run `docker-compose exec postgres sh -c 'pg_dump -cU $POSTGRES_USER $POSTGRES_DB' | gzip > db_dump.sql.gz`
2017-12-13 15:50:30 +01:00
* To restore that database backup run `gunzip -c db_dump.sql.gz | docker exec -i $(docker-compose ps -q postgres) sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'` .
### Getting a "Bad Request (400)"
2018-03-08 09:52:35 +01:00
> When connecting to the NetBox instance, I get a "Bad Request (400)" error.
2017-12-13 15:50:30 +01:00
This usually happens when the `ALLOWED_HOSTS` variable is not set correctly.
### How to upgrade
> How do I update to a newer version?
It should be sufficient to pull the latest image from Docker Hub, stopping the container and starting it up again:
```bash
docker-compose pull netbox
docker-compose stop netbox
docker-compose rm -f netbox
docker-compose up -d netbox
```
2018-04-04 13:13:41 +02:00
### Breaking Changes
2018-04-04 09:44:58 +02:00
From time to time it might become necessary to re-order the structure of the container.
Things like the `docker-compose.yml` file or your Kubernets or OpenShift configurations have to be adjusted as a consequence.
Since April 2018 each image built from this repo contains a `NETBOX_DOCKER_PROJECT_VERSION` label.
You can check the label of your local image by running `docker inspect ninech/netbox:v2.3.1 --format "{{json .ContainerConfig.Labels}}"` .
2018-04-04 13:13:41 +02:00
The following is a list of breaking changes:
2018-04-04 09:44:58 +02:00
2018-04-04 10:17:33 +02:00
* 0.2.0: Re-organized paths: `/etc/netbox -> /etc/netbox/config` and `/etc/reports -> /etc/netbox/reports` . Fixes [#54 ](https://github.com/ninech/netbox-docker/issues/54 ).
2018-04-04 13:13:41 +02:00
* 0.1.0: Introduction of the `NETBOX_DOCKER_PROJECT_VERSION` . (Not a breaking change per se.)
2018-04-04 09:44:58 +02:00
2017-09-11 15:30:52 +02:00
## Rebuilding & Publishing images
`./build.sh` is used to rebuild the Docker image:
```
$ ./build.sh --help
Usage: ./build.sh < branch > [--push]
branch The branch or tag to build. Required.
--push Pushes built Docker image to docker hub.
You can use the following ENV variables to customize the build:
BRANCH The branch to build.
Also used for tagging the image.
DOCKER_REPO The Docker registry (i.e. hub.docker.com/r/DOCKER_REPO/netbox)
Also used for tagging the image.
Default: ninech
SRC_REPO Which fork of netbox to use (i.e. github.com/< SRC_REPO > /netbox).
Default: digitalocean
URL Where to fetch the package from.
Must be a tar.gz file of the source code.
Default: https://github.com/${SRC_REPO}/netbox/archive/$BRANCH.tar.gz
```
2017-08-30 11:10:55 +02:00
## Tests
2018-03-08 09:52:35 +01:00
To run the test coming with NetBox, use the `docker-compose.test.yml` file as such:
2017-08-30 11:10:55 +02:00
```
2017-09-11 15:30:52 +02:00
$ docker-compose -f docker-compose.test.yml run --rm app
2017-08-30 11:10:55 +02:00
```
2017-09-11 15:30:52 +02:00
## About
2017-12-26 23:08:10 +01:00
This repository is currently maintained and funded by [nine ](https://nine.ch ), your cloud navigator.
2017-09-11 15:30:52 +02:00
2017-10-09 22:05:46 +02:00
[![logo of the company 'nine' ](https://logo.apps.at-nine.ch/Dmqied_eSaoBMQwk3vVgn4UIgDo=/trim/500x0/logo_claim.png )](https://www.nine.ch)