pi-hole/docs
1
0
Fork 0
mirror of https://github.com/pi-hole/docs.git synced 2024-12-06 19:27:12 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Tweaks following feedback

Browse Source 
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
This commit is contained in:
Adam Warner
2024-08-23 18:28:48 +00:00
committed by Adam Warner
parent 6e06b39dca
commit b730eaa6fa
1 changed files with 54 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/docker/build-image.md
+54 -41
View File
@@ -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 <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
### 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
```