2017-04-19 09:48:21 -05:00
# netbox-docker
2019-11-17 10:07:02 -06:00
[![GitHub release (latest by date) ](https://img.shields.io/github/v/release/netbox-community/netbox-docker )][github-release]
[![GitHub stars ](https://img.shields.io/github/stars/netbox-community/netbox-docker )][github-stargazers]
![GitHub closed pull requests ](https://img.shields.io/github/issues-pr-closed-raw/netbox-community/netbox-docker )
2020-01-23 02:35:30 -06:00
![Github release workflow ](https://img.shields.io/github/workflow/status/netbox-community/netbox-docker/release )
2019-11-17 10:07:02 -06:00
![Docker Pulls ](https://img.shields.io/docker/pulls/netboxcommunity/netbox )
[![GitHub license ](https://img.shields.io/github/license/netbox-community/netbox-docker )][netbox-docker-license]
2021-02-04 14:48:08 -06:00
[The Github repository ](netbox-docker-github ) houses the components needed to build NetBox as a Docker container.
2020-12-14 17:28:43 -06:00
Images are built using this code and are released to [Docker Hub][netbox-dockerhub] and [Quay.io][netbox-quayio] once a day.
2017-12-13 08:50:30 -06:00
2020-03-17 10:07:15 -05:00
Do you have any questions?
Before opening an issue on Github, please join the [Network To Code][ntc-slack] Slack and ask for help in our [`#netbox-docker`][netbox-docker-slack] channel.
2018-09-27 02:44:14 -05:00
2019-11-17 10:07:02 -06:00
[github-stargazers]: https://github.com/netbox-community/netbox-docker/stargazers
[github-release]: https://github.com/netbox-community/netbox-docker/releases
[netbox-docker-microbadger]: https://microbadger.com/images/netboxcommunity/netbox
2020-12-14 17:28:43 -06:00
[netbox-dockerhub]: https://hub.docker.com/r/netboxcommunity/netbox/
2019-10-12 08:16:17 -05:00
[netbox-docker-github]: https://github.com/netbox-community/netbox-docker/
2018-09-27 02:44:14 -05:00
[ntc-slack]: http://slack.networktocode.com/
2019-10-12 08:16:17 -05:00
[netbox-docker-slack]: https://slack.com/app_redirect?channel=netbox-docker& team=T09LQ7E9E
2020-01-23 03:26:21 -06:00
[netbox-docker-license]: https://github.com/netbox-community/netbox-docker/blob/release/LICENSE
2020-12-14 17:28:43 -06:00
[netbox-quayio]: https://quay.io/repository/netboxcommunity/netbox
2019-11-17 10:07:02 -06:00
## Docker Tags
2021-02-04 14:48:08 -06:00
* `vX.Y.Z` : These are release builds, automatically built from [the corresponding releases of NetBox][netbox-releases].
* `latest` : These are release builds, automatically built from [the `master` branch of NetBox][netbox-master].
* `snapshot` : These are pre-release builds, automatically built from the [`develop` branch of NetBox][netbox-develop].
* `develop-X.Y` : These are pre-release builds, automatically built from the corresponding [branch of NetBox][netbox-branches].
2019-11-17 10:07:02 -06:00
2020-03-17 10:07:15 -05:00
Then there is currently one extra tags for each of the above tags:
2019-11-17 10:07:02 -06:00
2021-02-04 14:48:08 -06:00
* `-ldap` : Contains additional dependencies and configurations for connecting NetBox to an LDAP directory.
2019-11-17 10:07:02 -06:00
[Learn more about that in our wiki][netbox-docker-ldap].
2020-03-17 10:07:15 -05:00
New images are built and published automatically every ~24h.
2019-11-17 10:07:02 -06:00
[netbox-releases]: https://github.com/netbox-community/netbox/releases
[netbox-master]: https://github.com/netbox-community/netbox/tree/master
[netbox-develop]: https://github.com/netbox-community/netbox/tree/develop
[netbox-branches]: https://github.com/netbox-community/netbox/branches
[netbox-docker-ldap]: https://github.com/netbox-community/netbox-docker/wiki/LDAP
2017-04-19 09:48:21 -05:00
## Quickstart
2021-02-04 14:48:08 -06:00
To get NetBox Docker up and running run the following commands.
2020-03-17 10:07:15 -05:00
There is a more complete [_Getting Started_ guide on our wiki][wiki-getting-started] which explains every step.
2017-04-19 09:48:21 -05:00
2019-07-02 14:32:58 -05:00
```bash
2019-12-10 14:44:11 -06:00
git clone -b release https://github.com/netbox-community/netbox-docker.git
2019-07-02 14:32:58 -05:00
cd netbox-docker
2020-04-22 15:24:34 -05:00
tee docker-compose.override.yml < < EOF
2020-03-17 10:07:15 -05:00
version: '3.4'
services:
2020-11-10 08:23:07 -06:00
netbox:
2020-03-17 10:07:15 -05:00
ports:
- 8000:8080
EOF
2019-07-02 14:32:58 -05:00
docker-compose pull
2020-03-17 10:07:15 -05:00
docker-compose up
2017-09-11 08:30:52 -05:00
```
2017-04-19 09:48:21 -05:00
2020-03-17 10:07:15 -05:00
The whole application will be available after a few minutes.
Open the URL `http://0.0.0.0:8000/` in a web-browser.
2021-02-04 14:48:08 -06:00
You should see the NetBox homepage.
2020-03-17 10:07:15 -05:00
In the top-right corner you can login.
2019-11-20 04:09:37 -06:00
The default credentials are:
2017-04-19 09:48:21 -05:00
* Username: **admin**
* Password: **admin**
2017-11-29 08:13:55 -06:00
* API Token: **0123456789abcdef0123456789abcdef01234567**
2017-04-19 09:48:21 -05:00
2019-11-20 04:09:37 -06:00
[wiki-getting-started]: https://github.com/netbox-community/netbox-docker/wiki/Getting-Started
2019-02-06 04:24:01 -06:00
[docker-reception]: https://github.com/nxt-engineering/reception
2017-12-13 08:50:30 -06:00
2020-03-17 10:07:15 -05:00
## Documentation
2021-02-04 14:48:08 -06:00
Please refer [to our wiki on Github][netbox-docker-wiki] for further information on how to use this NetBox Docker image properly.
2020-10-26 09:29:41 -05:00
It covers advanced topics such as using files for secrets, deployment to Kubernetes, monitoring and configuring NAPALM or LDAP.
2020-03-17 10:07:15 -05:00
[netbox-docker-wiki]: https://github.com/netbox-community/netbox-docker/wiki/
## Getting Help
2020-12-14 17:50:02 -06:00
Feel free to ask questions in our [Github Community][netbox-community] or join [our Slack channel `#netbox-docker` ][netbox-docker-slack] on the [Network To Code Slack][ntc-slack],
which is free to use and where there are almost always people online that can help you in the Slack channel.
2020-03-17 10:07:15 -05:00
2021-02-04 14:48:08 -06:00
If you need help with using NetBox or developing for it or against it's API you may find the `#netbox` channel on the same Slack instance very helpful.
2020-03-17 10:07:15 -05:00
2020-12-14 17:50:02 -06:00
[netbox-community]: https://github.com/netbox-community/netbox-docker/discussions
2017-10-16 06:09:17 -05:00
## Dependencies
2019-11-26 05:27:25 -06:00
This project relies only on *Docker* and *docker-compose* meeting these requirements:
2017-10-16 06:09:17 -05:00
2021-02-10 05:35:06 -06:00
* The *Docker version* must be at least `19.03` .
* The *docker-compose version* must be at least `1.28.0` .
2017-10-16 06:09:17 -05:00
2019-11-26 05:28:43 -06:00
To check the version installed on your system run `docker --version` and `docker-compose --version` .
2017-10-16 06:09:17 -05:00
2019-05-08 04:43:29 -05:00
## Breaking Changes
2018-04-04 02:44:58 -05:00
2018-08-13 16:04:09 -05:00
From time to time it might become necessary to re-engineer the structure of this setup.
Things like the `docker-compose.yml` file or your Kubernetes or OpenShift configurations have to be adjusted as a consequence.
2020-01-23 03:36:13 -06:00
2019-11-17 10:07:02 -06:00
Since November 2019 each image built from this repo contains a `org.opencontainers.image.version` label.
(The images contained labels since April 2018, although in November 2019 the labels' names changed.)
2020-01-23 03:36:13 -06:00
You can check the label of your local image by running `docker inspect netboxcommunity/netbox:v2.7.1 --format "{{json .Config.Labels}}"` .
2019-10-09 05:36:26 -05:00
Please read [the release notes][releases] carefully when updating to a new image version.
[releases]: https://github.com/netbox-community/netbox-docker/releases
2019-02-06 04:46:20 -06:00
2020-01-23 03:36:13 -06:00
## Rebuilding the Image
2017-09-11 08:30:52 -05:00
2019-02-06 04:24:01 -06:00
`./build.sh` can be used to rebuild the Docker image. See `./build.sh --help` for more information.
2017-08-30 04:10:55 -05:00
2020-01-23 03:36:13 -06:00
For more details on custom builds [consult our wiki][netbox-docker-wiki-build].
[netbox-docker-wiki-build]: https://github.com/netbox-community/netbox-docker/wiki/Build
2018-08-13 16:04:09 -05:00
2017-08-30 04:10:55 -05:00
## Tests
2020-01-23 03:36:13 -06:00
We have a test script.
2021-02-04 14:48:08 -06:00
It runs NetBox's own unit tests and ensures that all initializers work:
2017-08-30 04:10:55 -05:00
2019-07-02 14:32:58 -05:00
```bash
2020-01-23 03:36:13 -06:00
IMAGE=netboxcommunity/netbox:latest ./test.sh
2017-08-30 04:10:55 -05:00
```
2017-09-11 08:30:52 -05:00
## About
2019-02-06 04:46:20 -06:00
This repository is currently maintained and funded by [nxt][nxt].
[nxt]: https://nxt.engineering/en/