160 lines
7.2 KiB
Markdown
160 lines
7.2 KiB
Markdown
# netbox-docker
|
|
|
|
[][github-release]
|
|
[][github-stargazers]
|
|
|
|
|
|
|
|
[][netbox-docker-license]
|
|
|
|
[The GitHub repository][netbox-docker-github] houses the components needed to build NetBox as a container.
|
|
Images are built regularly using the code in that repository and are pushed to [Docker Hub][netbox-dockerhub], [Quay.io][netbox-quayio] and [GitHub Container Registry][netbox-ghcr].
|
|
|
|
Do you have any questions?
|
|
Before opening an issue on Github,
|
|
please join [our Slack][netbox-docker-slack] and ask for help in the [`#netbox-docker`][netbox-docker-slack-channel] channel.
|
|
|
|
[github-stargazers]: https://github.com/netbox-community/netbox-docker/stargazers
|
|
[github-release]: https://github.com/netbox-community/netbox-docker/releases
|
|
[netbox-dockerhub]: https://hub.docker.com/r/netboxcommunity/netbox/
|
|
[netbox-quayio]: https://quay.io/repository/netboxcommunity/netbox
|
|
[netbox-ghcr]: https://github.com/netbox-community/netbox-docker/pkgs/container/netbox
|
|
[netbox-docker-github]: https://github.com/netbox-community/netbox-docker/
|
|
[netbox-docker-slack]: https://join.slack.com/t/netdev-community/shared_invite/zt-mtts8g0n-Sm6Wutn62q_M4OdsaIycrQ
|
|
[netbox-docker-slack-channel]: https://netdev-community.slack.com/archives/C01P0GEVBU7
|
|
[netbox-slack-channel]: https://netdev-community.slack.com/archives/C01P0FRSXRV
|
|
[netbox-docker-license]: https://github.com/netbox-community/netbox-docker/blob/release/LICENSE
|
|
|
|
## Quickstart
|
|
|
|
To get _NetBox Docker_ up and running run the following commands.
|
|
There is a more complete [_Getting Started_ guide on our wiki][wiki-getting-started] which explains every step.
|
|
|
|
```bash
|
|
git clone -b release https://github.com/netbox-community/netbox-docker.git
|
|
cd netbox-docker
|
|
tee docker-compose.override.yml <<EOF
|
|
services:
|
|
netbox:
|
|
ports:
|
|
- 8000:8080
|
|
EOF
|
|
docker compose pull
|
|
docker compose up
|
|
```
|
|
|
|
The whole application will be available after a few minutes.
|
|
Open the URL `http://0.0.0.0:8000/` in a web-browser.
|
|
You should see the NetBox homepage.
|
|
|
|
To create the first admin user run this command:
|
|
|
|
```bash
|
|
docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser
|
|
```
|
|
|
|
If you need to restart Netbox from an empty database often, you can also set the `SUPERUSER_*` variables in your `docker-compose.override.yml` as shown in the example.
|
|
|
|
[wiki-getting-started]: https://github.com/netbox-community/netbox-docker/wiki/Getting-Started
|
|
|
|
## Container Image Tags
|
|
|
|
New container images are built and published automatically every ~24h.
|
|
|
|
> We recommend to use either the `vX.Y.Z-a.b.c` tags or the `vX.Y-a.b.c` tags in production!
|
|
|
|
* `vX.Y.Z-a.b.c`, `vX.Y-a.b.c`:
|
|
These are release builds containing _NetBox version_ `vX.Y.Z`.
|
|
They contain the support files of _NetBox Docker version_ `a.b.c`.
|
|
You must use _NetBox Docker version_ `a.b.c` to guarantee the compatibility.
|
|
These images are automatically built from [the corresponding releases of NetBox][netbox-releases].
|
|
* `latest-a.b.c`:
|
|
These are release builds, containing the latest stable version of NetBox.
|
|
They contain the support files of _NetBox Docker version_ `a.b.c`.
|
|
You must use _NetBox Docker version_ `a.b.c` to guarantee the compatibility.
|
|
These images are automatically built from [the `master` branch of NetBox][netbox-master].
|
|
* `snapshot-a.b.c`:
|
|
These are prerelease builds.
|
|
They contain the support files of _NetBox Docker version_ `a.b.c`.
|
|
You must use _NetBox Docker version_ `a.b.c` to guarantee the compatibility.
|
|
These images are automatically built from the [`develop` branch of NetBox][netbox-develop].
|
|
|
|
For each of the above tag, there is an extra tag:
|
|
|
|
* `vX.Y.Z`, `vX.Y`:
|
|
This is the same version as `vX.Y.Z-a.b.c` (or `vX.Y-a.b.c`, respectively).
|
|
It always points to the latest version of _NetBox Docker_.
|
|
* `latest`
|
|
This is the same version as `latest-a.b.c`.
|
|
It always points to the latest version of _NetBox Docker_.
|
|
* `snapshot`
|
|
This is the same version as `snapshot-a.b.c`.
|
|
It always points to the latest version of _NetBox Docker_.
|
|
|
|
[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
|
|
|
|
## Documentation
|
|
|
|
Please refer [to our wiki on GitHub][netbox-docker-wiki] for further information on how to use the NetBox Docker image properly.
|
|
The wiki covers advanced topics such as using files for secrets, configuring TLS, deployment to Kubernetes, monitoring and configuring LDAP.
|
|
|
|
Our wiki is a community effort.
|
|
Feel free to correct errors, update outdated information or provide additional guides and insights.
|
|
|
|
[netbox-docker-wiki]: https://github.com/netbox-community/netbox-docker/wiki/
|
|
|
|
## Getting Help
|
|
|
|
Feel free to ask questions in our [GitHub Community][netbox-community]
|
|
or [join our Slack][netbox-docker-slack] and ask [in our channel `#netbox-docker`][netbox-docker-slack-channel],
|
|
which is free to use and where there are almost always people online that can help you in the Slack channel.
|
|
|
|
If you need help with using NetBox or developing for it or against it's API
|
|
you may find [the `#netbox` channel][netbox-slack-channel] on the same Slack instance very helpful.
|
|
|
|
[netbox-community]: https://github.com/netbox-community/netbox-docker/discussions
|
|
|
|
## Dependencies
|
|
|
|
This project relies only on _Docker_ and _docker-compose_ meeting these requirements:
|
|
|
|
* The _Docker version_ must be at least `20.10.10`.
|
|
* The _containerd version_ must be at least `1.5.6`.
|
|
* The _docker-compose version_ must be at least `1.28.0`.
|
|
|
|
To check the version installed on your system run `docker --version` and `docker compose version`.
|
|
|
|
## Updating
|
|
|
|
Please read [the release notes][releases] carefully when updating to a new image version.
|
|
Note that the version of the NetBox Docker container image must stay in sync with the code.
|
|
|
|
If you update for the first time, be sure [to follow our _How To Update NetBox Docker_ guide in the wiki][netbox-docker-wiki-updating].
|
|
|
|
[releases]: https://github.com/netbox-community/netbox-docker/releases
|
|
[netbox-docker-wiki-updating]: https://github.com/netbox-community/netbox-docker/wiki/Updating
|
|
|
|
## Rebuilding the Image
|
|
|
|
`./build.sh` can be used to rebuild the container image. See `./build.sh --help` for more information.
|
|
|
|
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
|
|
|
|
## Tests
|
|
|
|
We have a test script.
|
|
It runs NetBox's own unit tests and ensures that all initializers work:
|
|
|
|
```bash
|
|
IMAGE=netboxcommunity/netbox:latest ./test.sh
|
|
```
|
|
|
|
## Support
|
|
|
|
This repository is currently maintained by the community.
|
|
Please consider sponsoring the maintainers of this project.
|