Created Build (markdown)

Build.md

@@ -0,0 +1,73 @@
+**THIS TEXT IS CURRENTLY A DRAFT** and applies to the MRs [#159][159] and [#164][164]
+
+[159]: https://github.com/netbox-community/netbox-docker/pull/159
+[164]: https://github.com/netbox-community/netbox-docker/pull/164
+
+This document describes two different intentions:
+
+- *Enhance the image*: Adjust the existing Docker image to your organization's needs.
+  This can reduce the number of environment variables you'd have to configure or you can ship a default configuration by embedding your initializer yaml files.
+- *Build the image from scratch*: This is mostly useful to you when you work on `netbox-docker` itself.
+
+## Enhance the image
+
+The purpose of enhancing the image is usually to embed additional scripts or change the default configuration file.
+This usually works by using the `netboxcommunity/netbox` image as base image:
+
+```Dockerfile
+FROM netboxcommunity/netbox:v2.6.6
+
+COPY my_configuration.py /etc/netbox/config/configuration.py
+COPY my_startup_scripts/ /opt/netbox/startup_scripts/
+COPY my_initializers/ /opt/netbox/initializers/
+COPY my_reports/ /etc/netbox/reports/
+COPY my_scripts/ /etc/netbox/scripts
+```
+
+You don't have to add all the files.
+But usually you'd use a selection of them.
+
+## Build the Image from Scratch
+
+The `netbox-docker` image is very advanced and has a rather complex build system.
+That's why all of the complexity was captured in a few files:
+
+- **`build.sh`**: This script is called by all the others. Run `./build.sh --help` to see all the options.
+- **`build-all.sh`**: This script builds all versions of the Netbox Docker Image, i.e. releases (e.g. `v2.6.6`), pre-releases (e.g. `v2.6-beta1`), `latest` and `snapshot`.
+- **`build-branches.sh`**: Builds the `master` Git branch as `latest`, the `develop` Git branch as `snapshot` and the `develop-*` branch 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`.
+
+### Oldschool `docker build`
+
+You can still build the image manually using `docker build`.
+If you want to do that, you must pass at least one build argument to Docker:
+The `NETBOX_PATH`.
+This build argument must be a path to a folder that contains all the Netbox files.
+
+So, full instructions would look like this:
+
+```bash
+git clone https://github.com/netbox-community/netbox-docker.git
+cd netbox-docker
+git clone https://github.com/netbox-community/netbox.git netbox
+docker build --build-args "NETBOX_PATH=netbox" --target main .
+```
+
+### 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 on Docker Hub, which are trigger once a day and on every commit to the `master` branch of `netbox-docker`.
+
+This automatic build relies on the same `/build*.sh` files as described above.
+The default commands of Docker Hub are overwritten using the files in `/hooks/*`.
+
+To learn more about the automatic builds read the [`DOCKER_HUB.md`][hub] file.
+
+[hub]: https://github.com/netbox-community/netbox-docker/blob/master/DOCKER_HUB.md