From c4cb141ce5543dc8d3e43b38b7db4c69d295c7e3 Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Fri, 23 Aug 2024 17:58:07 +0000 Subject: [PATCH 1/5] Add some information about building the docker image locally Signed-off-by: Adam Warner --- docs/docker/build-image.md | 66 ++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 67 insertions(+) create mode 100644 docs/docker/build-image.md diff --git a/docs/docker/build-image.md b/docs/docker/build-image.md new file mode 100644 index 000000000..1de75952b --- /dev/null +++ b/docs/docker/build-image.md @@ -0,0 +1,66 @@ +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) + +#### 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 + `-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, and an image will be created based on the current branch of the repository, and all `master` component branches. + +``` +docker buildx build src/. --tag pihole --no-cache +``` + +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: + +```yml +services: + pihole: + container_name: pihole + image: pihole +... +``` + +``` +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 +``` 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 From e4c6e35a2a3c1e2e235fbe86829d2b7c0d909eee Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Fri, 23 Aug 2024 18:28:48 +0000 Subject: [PATCH 2/5] Tweaks following feedback Signed-off-by: Adam Warner --- docs/docker/build-image.md | 79 ++++++++++++++++++++++---------------- 1 file changed, 46 insertions(+), 33 deletions(-) diff --git a/docs/docker/build-image.md b/docs/docker/build-image.md index 1de75952b..a784b8a4c 100644 --- a/docs/docker/build-image.md +++ b/docs/docker/build-image.md @@ -1,66 +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 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 -``` -docker buildx build src/. --tag pihole --no-cache -``` +### Contributing to the development of `docker-pi-hole` -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: +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. -```yml -services: - pihole: - container_name: pihole - image: pihole -... -``` +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 run [options] pihole +git checkout -b myNewFeatureBranch +#make some changes +./build.sh ``` -Then start your container as normal. - -### `pihole checkout` alternative +### 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. -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 ``` + +## 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: + pihole: + container_name: pihole + image: pihole +... +``` + +``` +docker run [options] pihole +``` From a6866049f3deae0da3d5d793e4da90e37d30606e Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Sat, 24 Aug 2024 18:17:43 +0100 Subject: [PATCH 3/5] Update docs/docker/build-image.md Co-authored-by: yubiuser Signed-off-by: Adam Warner --- docs/docker/build-image.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docker/build-image.md b/docs/docker/build-image.md index a784b8a4c..969e48f17 100644 --- a/docs/docker/build-image.md +++ b/docs/docker/build-image.md @@ -66,7 +66,7 @@ git checkout fix/logRotate 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 +```yaml services: pihole: container_name: pihole From 86d1814c2fed933184779eedbcd28c2ede849a77 Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Sun, 25 Aug 2024 12:47:40 +0000 Subject: [PATCH 4/5] Update local image name following https://github.com/pi-hole/docker-pi-hole/pull/1628 Signed-off-by: Adam Warner --- docs/docker/build-image.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docker/build-image.md b/docs/docker/build-image.md index 969e48f17..902a75ab9 100644 --- a/docs/docker/build-image.md +++ b/docs/docker/build-image.md @@ -21,12 +21,12 @@ Options: -c, --corebranch Specify Core branch -w, --webbranch Specify Web branch -p, --paddbranch Specify PADD branch - -t, --tag Specify Docker image tag (default: pihole) + -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 --load --no-cache + docker buildx build src/. --tag pihole:local --load --no-cache ``` ## Example uses of the script @@ -64,16 +64,16 @@ git checkout fix/logRotate ## 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: +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 + image: pihole:local ... ``` ``` -docker run [options] pihole +docker run [options] pihole:local ``` From 424ddf640659af19c58b8563a0afa5dbe63f6df5 Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Wed, 11 Sep 2024 22:02:12 +0100 Subject: [PATCH 5/5] development-v6 -> development --- docs/docker/build-image.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docker/build-image.md b/docs/docker/build-image.md index 902a75ab9..69db5068c 100644 --- a/docs/docker/build-image.md +++ b/docs/docker/build-image.md @@ -7,7 +7,7 @@ In order to build the image locally, you will first need a copy of the repositor ``` 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 +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.