From 7a3fdfc8b93c0beb4f22cd1b74e3458848b68050 Mon Sep 17 00:00:00 2001 From: Adam Warner Date: Mon, 1 Jan 2018 19:14:34 +0000 Subject: [PATCH] some tweaks and fleshing out Signed-off-by: Adam Warner --- docs/main/basic-install.md | 22 ++++++++++++++++++++ docs/main/post-install.md | 7 +++++++ docs/main/prerequesites.md | 41 ++++++++++++++++++++++++++++++++++++++ docs/prerequesites.md | 0 mkdocs.yml | 9 ++++++--- 5 files changed, 76 insertions(+), 3 deletions(-) create mode 100644 docs/main/basic-install.md create mode 100644 docs/main/post-install.md create mode 100644 docs/main/prerequesites.md delete mode 100644 docs/prerequesites.md diff --git a/docs/main/basic-install.md b/docs/main/basic-install.md new file mode 100644 index 0000000..6fdaeb4 --- /dev/null +++ b/docs/main/basic-install.md @@ -0,0 +1,22 @@ +## One-Step Automated Install +Those who want to get started quickly and conveniently, may install Pi-hole using the following command: + +```BASH +curl -sSL https://install.pi-hole.net | bash +``` + +## Alternative Install Methods +[Piping to `bash` is controversial](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash), as it prevents you from [reading code that is about to run](https://github.com/pi-hole/pi-hole/blob/master/automated%20install/basic-install.sh) on your system. Therefore, we provide these alternative installation methods which allow code review before installation: + +### Method 1: Clone our repository and run +```BASH +git clone --depth 1 https://github.com/pi-hole/pi-hole.git Pi-hole +cd "Pi-hole/automated install/" +sudo bash basic-install.sh +``` + +### Method 2: Manually download the installer and run +```BASH +wget -O basic-install.sh https://install.pi-hole.net +sudo bash basic-install.sh +``` \ No newline at end of file diff --git a/docs/main/post-install.md b/docs/main/post-install.md new file mode 100644 index 0000000..6df2933 --- /dev/null +++ b/docs/main/post-install.md @@ -0,0 +1,7 @@ +## Post-install: Make your network take advantage of Pi-hole + +Once the installer has been run, you will need to [configure your router to have **DHCP clients use Pi-hole as their DNS server**](https://discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245) which ensures that all devices connecting to your network will have content blocked without any further intervention. + +If your router does not support setting the DNS server, you can [use Pi-hole's built in DHCP server](https://discourse.pi-hole.net/t/how-do-i-use-pi-holes-built-in-dhcp-server-and-why-would-i-want-to/3026); just be sure to disable DHCP on your router first (if it has that feature available). + +As a last resort, you can always manually set each device to use Pi-hole as their DNS server. \ No newline at end of file diff --git a/docs/main/prerequesites.md b/docs/main/prerequesites.md new file mode 100644 index 0000000..6ba2e94 --- /dev/null +++ b/docs/main/prerequesites.md @@ -0,0 +1,41 @@ +###Hardware +Pi-hole is very lightweight, and does not require much processing power + +- ~52MB of free space +- 512MB RAM + +Despite the name, you are not limited to running Pi-hole on a Raspberry Pi. +Any hardware that runs one of the supported operating systems will do! + +###Supported Operating Systems + +The following operating systems are **officially** supported: + +- Raspbian: Jessie / Stretch +- Ubuntu: 16.04 / 16.10 +- Fedora: 26 / 27 +- Debian: 8 / 9 +- CentOS: 7 (not ARM) + +###IP Addressing + +Pi-hole needs a static IP address to properly function (a DHCP reservation is just fine). Users may run into issues because **we currently install `dhcpcd5`, which may conflict with other running network managers** such as `dhclient`, `dhcpcd`, `networkmanager`, and `systemd-networkd`. + +As part of our install process, **we append some lines to `/etc/dhcpcd.conf` in order to statically assign an IP address**, so take note of this prior to installing. + +Please be aware of this fact because it [may cause confusion](https://github.com/pi-hole/pi-hole/issues/1713#issue-260746084). This is not the ideal situation for us to be in, but since a significant portion of our users are running Pi-hole on Raspbian; and because Pi-hole's roots began with the Raspberry Pi, it's a problem that is [difficult problem to get away from](https://github.com/pi-hole/pi-hole/issues/1713#issuecomment-332317532). + +Due to the complexity of different ways of setting an IP address across different systems, it's a slow process and [we need help](https://github.com/pi-hole/pi-hole/issues/629). If you're willing to contribute, please let us know. + +###Ports + +We need ports _53_, _80_, and _4711_. Port _80_ is optional if you decide not to install the Web dashboard during installation. + +**Port 53 should be used by `dnsmasq`** +If you happen to have another DNS server running, such as BIND, you will need to turn it off in order for Pi-hole to respond to DNS queries. + +**Port 80 should be used by `lighttpd`** +If you have another Web server already running, such as Apache, Pi-hole's Web server will not work. You can either disable the other Web server or change the port on which `lighttpd` listens, which allows you keep both Web servers running. + +**Port 4711 should be used by `pihole-FTL`** +FTL is our API engine and by default uses port 4711, but will increment if it's already in use by something else. diff --git a/docs/prerequesites.md b/docs/prerequesites.md deleted file mode 100644 index e69de29..0000000 diff --git a/mkdocs.yml b/mkdocs.yml index 31b6046..24d0954 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,10 +6,13 @@ repo_name: pi-hole/docs repo_url: https://github.com/pi-hole/docs edit_uri: ../docs/edit/master/docs/ remote_branch: gh-pages -theme: material +theme: readthedocs pages: -- 'Information & Support': 'index.md' -- 'Prerequisites': 'prerequesites.md' +- 'Support': 'index.md' +- 'Getting Started': + - 'Prerequisites': 'main/prerequesites.md' + - 'Installation': 'main/basic-install.md' + - 'Post-Install': 'main/post-install.md' - 'Guides': - 'Pi-hole and OpenVPN Server': - 'Overview': 'guides/vpn/overview.md'