diff --git a/docs/docker/build-image.md b/docs/docker/build-image.md new file mode 100644 index 000000000..69db5068c --- /dev/null +++ b/docs/docker/build-image.md @@ -0,0 +1,79 @@ +In case you wish to customise the image, or perhaps check out a branch after being asked by a developer to do so, you can use the convenient `build.sh` script located in the root of the [docker-pi-hole repository](https://github.com/pi-hole/docker-pi-hole) + +## Checking out the repository + +In order to build the image locally, you will first need a copy of the repository on your computer. The following commands will clone the repository from Github and then put you into the directory + +``` +git clone https://github.com/pi-hole/docker-pi-hole +cd docker-pi-hole +git checkout development #NOTE: This step is only needed until V6 is released +``` + +All other commands following assume you have at least run the above steps. + +## Build.sh + +``` +Usage: ./build.sh [-l] [-f ] [-c ] [-w ] [-t ] [use_cache] +Options: + -f, --ftlbranch Specify FTL branch (cannot be used in conjunction with -l) + -c, --corebranch Specify Core branch + -w, --webbranch Specify Web branch + -p, --paddbranch Specify PADD branch + -t, --tag Specify Docker image tag (default: pihole:local) + -l, --local Use locally built FTL binary (requires src/pihole-FTL file) + use_cache Enable caching (by default --no-cache is used) + +If no options are specified, the following command will be executed: + docker buildx build src/. --tag pihole:local --load --no-cache +``` + +## Example uses of the script + +### Contributing to the development of `docker-pi-hole` + +When contributing, it's always a good idea to test your changes before submitting a pull request. Simply running `./build.sh` will allow you to do so. + +There is also `./build-and-test.sh`, which can be used to verify the tests that are run on Github pass with your changes. + +``` +git checkout -b myNewFeatureBranch +#make some changes +./build.sh +``` + +### As an alternative to `pihole checkout` + +Occasionally you may need to try an alternative branch of one of the components (`core`,`web`,`ftl`). On bare metal you would run, for example, `pihole checkout core branchName`, however in the Docker image we have disabled this command as it can cause unpredictable results. + +#### Examples + +- You have been asked by a developer to checkout the FTL branch `new/Sensors`. To do so + +``` +./build.sh -f new/Sensors +``` + +- There is new docker-specific work being carried out on the branch `fix/logRotate` that you wish to test + +``` +git checkout fix/logRotate +./build.sh +``` + +## Using the built image + +Unless otherwise named via the `-t` command, the script will build an image locally and tag it as `pihole:local`. You can reference this as a drop-in replacement for `pihole/pihole:latest` in your compose file or your run command: + +```yaml +services: + pihole: + container_name: pihole + image: pihole:local +... +``` + +``` +docker run [options] pihole:local +``` diff --git a/mkdocs.yml b/mkdocs.yml index 0bfc43e01..7aeea9cd4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -158,6 +158,7 @@ nav: - "Pi-hole extensions": regex/pi-hole.md - "Approximate matching": regex/approximate.md - 'Docker': + - 'Building': docker/build-image.md - 'DHCP': docker/DHCP.md - 'Contributing': - 'Contributing on GitHub': guides/github/contributing.md