From b730eaa6fa2c5cb75e34a79eeb56fd5c980e7927 Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Fri, 23 Aug 2024 18:28:48 +0000 Subject: [PATCH] Tweaks following feedback Signed-off-by: Adam Warner --- docs/docker/build-image.md | 95 ++++++++++++++++++++++---------------- 1 file changed, 54 insertions(+), 41 deletions(-) diff --git a/docs/docker/build-image.md b/docs/docker/build-image.md index 1de7595..a784b8a 100644 --- a/docs/docker/build-image.md +++ b/docs/docker/build-image.md @@ -1,29 +1,70 @@ -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 convienient `build.sh` script located in the root of the [docker-pi-hole repository](https://github.com/pi-hole/docker-pi-hole) +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) -#### Usage: +## 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 ``` -./build.sh [-l] [-f ] [-c ] [-w ] [-t ] [use_cache] +git clone https://github.com/pi-hole/docker-pi-hole +cd docker-pi-hole +git checkout development-v6 #NOTE: This step is only needed until V6 is released ``` -#### Options: +All other commands following assume you have at least run the above steps. + +## Build.sh ``` - `-f ` / `--ftlbranch `: Specify FTL branch (cannot be used in conjunction with `-l`) - `-c ` / `--corebranch `: Specify Core branch - `-w ` / `--webbranch `: Specify Web branch - `-t ` / `--tag `: Specify Docker image tag (default: `pihole`) - `-l` / `--local`: Use locally built FTL binary (requires `src/pihole-FTL` file) - `use_cache`: Enable caching (by default `--no-cache` is used) +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) + -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 --load --no-cache ``` -If no options are specified, the following command will be executed, and an image will be created based on the current branch of the repository, and all `master` component branches. +## 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. ``` -docker buildx build src/. --tag pihole --no-cache +git checkout -b myNewFeatureBranch +#make some changes +./build.sh ``` -Once the command has run, a local image will have been created named `pihole`, you can reference this as a drop-in replacement for `pihole/pihole:latest` in your compose file or your run command: +### 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`. You can reference this as a drop-in replacement for `pihole/pihole:latest` in your compose file or your run command: ```yml services: @@ -36,31 +77,3 @@ services: ``` docker run [options] pihole ``` - -Then start your container as normal. - -### `pihole checkout` alternative - -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. - -The preferred method is to use the script documented above - -#### Examples - -- You have been asked by a developer to checkout the FTL branch `new/Sensors`. To do so - -``` -git clone https://github.com/pi-hole/docker-pi-hole -cd docker-pi-hole -git checkout development-v6 # NOTE: This step is only needed until V6 is released -./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 clone https://github.com/pi-hole/docker-pi-hole -cd docker-pi-hole -git checkout fix/logRotate -./build.sh -```