15 Build

Florian Heigl edited this page 2024-09-09 20:09:51 +02:00

Table of Contents

• Which build do you need?
• Extend the Image
• Build the Image from Scratch
• Build Targets
• Automatic Build

This document describes two different intentions:

• Extend the image: Adjust the existing Docker image to the needs of your organization. This can reduce the number of environment variables you have to configure.
• Build the image from scratch: This is mostly useful to you when you work on netbox-docker itself.

Which build do you need?

tl;dr: You need the Extend the image build.

• Custom Configuration File: Extend the image
• Additional Files: Extend the image
• Custom Nginx Configuration: Either build your own nginx-based Docker image or extend the netbox-docker image
• NetBox Plugin: Extend the image
  • ⚠️ See the extra guide Using NetBox Plugins
• Using many plugins / track upstream plugins: Build the Image from Scratch
• Develop NetBox : Build the Image from Scratch

Extend the Image

The purpose of enhancing the image is usually to embed additional scripts, change the default configuration file or add a Netbox plugin. This usually works by using the netboxcommunity/netbox image as base image:

FROM netboxcommunity/netbox:v2.6.6

COPY my_configuration.py /etc/netbox/config/extra_configuration.py
COPY my_reports/ /etc/netbox/reports/
COPY my_scripts/ /etc/netbox/scripts/

You don't have to add all the files. Usually you will only copy (and maybe overwrite) the files which you need to adjust.

Build the Image from Scratch

Hint: Unless you work on NetBox itself there should be no reason for re-building the image from scratch for your own purposes.

The netbox-docker Docker image has a rather complex build system. That's why all of the complexity is captured in a few build scripts:

• build.sh: This is the main build script. It is called by all the other scripts. Run ./build.sh --help to see all the options.
• build-next.sh: Builds the master Git branch as latest, the develop Git branch as snapshot and the develop-* branches as develop-*.
• build-latest.sh: Queries Github to get the most recent tag. When launched with PRERELEASE=true it will build a pre-release tag (usually beta releases) if the version of the pre-release is newer than the newest release tag. This produces a version like v2.6.6 and also tags v2.6.

Build Targets

The Docker file knows multiple build targets:

• builder: It's goal is to compile all the Python dependencies. Thereby the other targets can be kept slimmer because they don't need to have all the build dependencies installed. It's also good for caching.
• main: Extends builder and adds all the NetBox code and all the configuration files.
• ldap: Extends main and adds ldap-related dependencies and configuration files.

Automatic Build

There are automatic builds configured based on Github Actions, which are trigger once a day and on every commit to the master branch of netbox-docker.

The automatic build relies on the same /build*.sh files as described above.