-
-
Notifications
You must be signed in to change notification settings - Fork 210
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Adam Warner <[email protected]>
- Loading branch information
Showing
1 changed file
with
46 additions
and
33 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <ftl_branch>] [-c <core_branch>] [-w <web_branch>] [-t <tag>] [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 <branch>` / `--ftlbranch <branch>`: Specify FTL branch (cannot be used in conjunction with `-l`) | ||
| `-c <branch>` / `--corebranch <branch>`: Specify Core branch | ||
| `-w <branch>` / `--webbranch <branch>`: Specify Web branch | ||
| `-t <tag>` / `--tag <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 <ftl_branch>] [-c <core_branch>] [-w <web_branch>] [-t <tag>] [use_cache] | ||
| Options: | ||
| -f, --ftlbranch <branch> Specify FTL branch (cannot be used in conjunction with -l) | ||
| -c, --corebranch <branch> Specify Core branch | ||
| -w, --webbranch <branch> Specify Web branch | ||
| -p, --paddbranch <branch> Specify PADD branch | ||
| -t, --tag <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 | ||
| ``` |