Improved Docker documentation

[JaneX8]

This is a...

• Request for a new or modified feature
• Issue trying to run the docker image
• Issue trying to build / test / develop the docker image

Description

I love this project. I have spend hours yesterday setting it up, especially the DHCP part inside a Docker container (along with some nice limitations of my ISPs router) made it quite time consuming. I've spend hours reading a lot of issues and examples on this Github pages. I think we could improve the documentation especially when it comes to running the DHCP server from within Docker. Also, from stopping, restarting docker with the proper arguments and persisting data.

Expected Behavior

We should improve the Docker documentation to include instructions on how to Stop, Remove, but especially Restart the Docker container properly without loosing states or data. Also we should be more specific about the proper settings that needs to be used in Docker to get DHCP working.

Actual Behavior

Had to read many (older) issues here, test, trial and error. Took quite some research to get to identify the issues and get the proper information.

Possible Fix

Improved documentation.

Steps to Reproduce and debugging done

e.g. your docker run command, pages to visit, CLI commands you ran
After a lot of trial and error I found that my near perfect command would be:

docker run -d \
    --name pihole \
    -e ServerIP="192.168.178.10" \
    -e TZ="Europe/Amsterdam" \
    -v "/media/someMountedDisk/pihole/etc-pihole/:/etc/pihole/" \
    -v "/media/someMountedDisk/pihole/etc-dnsmasq.d/:/etc/dnsmasq.d/" \
    --dns=127.0.0.1 \
    --dns=1.1.1.1 \
    --net=host \
    --cap-add=NET_ADMIN \
    --cap-add=CAP_NET_BROADCAST \
    --restart=unless-stopped \
pihole/pihole:latest

But I am still not sure if the two dns options are required, if the CAP_NET_BROADCAST is required or NET_ADMIN is enough but surely without both it won't work. Also I've read that the ServerIP was required for DHCP to work properl. Also I've experienced twice that all my settings were gone after a restart. I would appreciate proper docker commands for setting it up the first time, stopping, removing, restarting et cetera without losing data. I'm also still doubting if I mounted enough proper folders and how to stop/start the container without losing my configuration and statistics.

Debug steps I have tried

• I have tried destroying my container instance, pulling the newest image version, and re-creating a new container
• I have tried running the nearly stock docker run example in the readme (removing any customizations I added)
• I have tried running without my volume data mounts to eliminate volumes as the cause
• I have searched this repository for existing issues and pull requests that look similar

Context and extra information

Your Environment

• Docker Host Operating System and OS Version:
• Docker Version:
• Hardware architecture:

I use the latest Docker version on Ubuntu 18.04.4 LTS (bionic).

[rhee876527]

Bump. After bashing my head against the wall for hours trying to make DHCP work. Seems the current implementation of DHCP that works for me (tested with 5.0 and 4.4) is from exactly what you have shared above. Except in my case, only works when I additionally include a web port env - -e WEB_PORT=xxx .Leaving this here in case anyone faces the same issue I had. @diginc

[github-actions]

This issue is stale because it has been open 30 days with no activity. Please comment or update this issue or it will be closed in 5 days.

[JaneX8]

Keep open. This is still ongoing.

[PromoFaux]

if the CAP_NET_BROADCAST is required or NET_ADMIN is enough

NET_ADMIN should be enough here.

Pull requests are welcome with any improvements to the docs, though I do agree they could do with some updating.

I actually want to get the readme migrated into "proper" docs over at HTTPS://docs.pi-hole.net, but it's an arduous task that I've not yet found the time for