Skip to content

Update README.md #1848

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: development
Choose a base branch
from
Open

Update README.md #1848

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
15d798a
Update README.md
jcstang Jun 13, 2025
8947197
Update README.md
jcstang Jun 17, 2025
1ecc94b
Merge branch 'development' into master
jcstang Jun 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ The standard Pi-hole customization abilities apply to this docker, but with dock

Do not attempt to upgrade (`pihole -up`) or reconfigure (`pihole -r`).

New images will be released for upgrades, upgrading by replacing your old container with a fresh upgraded image is the 'docker way'. Long-living docker containers are not the docker way since they aim to be portable and reproducible, why not re-create them often! Just to prove you can.
New images will be released for upgrades, upgrading by replacing your old container with a fresh upgraded image is the 'docker way'. Long-living docker containers are not the docker way since they aim to be portable and reproducible, why not re-create them often! **Just to prove you can.**
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why did you change the styling here?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just meant to change the styling for "Just to prove you can.". Thought an emphasis on this phrase would be impactful.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
New images will be released for upgrades, upgrading by replacing your old container with a fresh upgraded image is the 'docker way'. Long-living docker containers are not the docker way since they aim to be portable and reproducible, why not re-create them often! **Just to prove you can.**
New images will be released for upgrades, upgrading by replacing your old container with a fresh upgraded image is the 'docker way'. Long-living docker containers are not the docker way since they aim to be portable and reproducible, why not re-create them often!

I think this could even be removed.


0. Read the release notes for both this Docker release and the Pi-hole release
- This will help you avoid common problems due to any known issues with upgrading or newly required arguments or variables
Expand All @@ -252,7 +252,7 @@ New images will be released for upgrades, upgrading by replacing your old contai
2. Throw away your container: `docker rm -f pihole`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
2. Throw away your container: `docker rm -f pihole`
2. Throw away your container: `docker compose down`

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably switch this up for a compose command, too. Otherwise it doesn't make a lot of sense in the grand scheme of things.

Copy link
Member

@rdwebdesign rdwebdesign Jul 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm undecided here... We have a few places suggesting docker run commands and arguments in the Docs and in the README:

Maybe we could suggest both commands:

Suggested change
2. Throw away your container: `docker rm -f pihole`
2. Throw away your container: `docker rm -f pihole` or `docker compose down`, depending on how you started your container.

And also change the step 3., adding:

-3. Start your container with the newer base image: `docker compose up -d` 
+3. Start your container with the newer base image: `docker compose up -d` or `docker run <args>`

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would switch everything to compose syntax. Are users really running docker run by hand with all the necessary options/flags?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are users really running docker run

The trick is never to be surprised, and then they cannot surprise you.

Copy link
Contributor

@casperklein casperklein Sep 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can avoid the docker compose down step by using: docker compose pull && docker compose up --force-recreate

https://docs.docker.com/reference/cli/docker/compose/up/

Edit:

Or as a one-liner: docker compose up --force-recreate --pull always -d

This downloads the latest image, stops and removes the currently running container, creates a new one, and starts it.

- **Warning:** When removing your pihole container you may be stuck without DNS until step 3; **`docker pull`** before **`docker rm -f`** to avoid DNS interruption.
- If you care about your data (logs/customizations), make sure you have it volume-mapped or it will be deleted in this step.
3. Start your container with the newer base image: `docker run <args> pihole/pihole` (`<args>` being your preferred run volumes and env vars)
3. Start your container with the newer base image: `docker run <args> pihole/pihole` (`<args>` being your preferred run volumes and env vars). **OR** `docker compose up -d` if you have a `docker-compose.yml` file.

**Why is this style of upgrading good?**

Expand Down