pihole/web-build repository overview

⁠Pi-hole Web Interface

View stats and control your Pi-hole via this web interface. For the previous PHP-based web interface, see pi-hole/AdminLTE⁠.

⁠Web Preview⁠

⁠Changes compared to the AdminLTE interface

• Eliminates the reliance on server-side rendering scripts
• Eliminates spaghetti code resulted from heavily modifying the base AdminLTE template
• Reduces attack vectors by forcing interactions to go through an API instead of directly calling server functions.
• Makes it easier for new developers to figure out the code, which speeds up development
• Makes the split between client and server code much more explicit
• Allows us to easily generate fake data for testing
• Includes all the benefits that come from React (ES6 JavaScript), including automatic DOM manipulations and reusable components

⁠Getting Started (Development)

• Install Node.js + npm (usually installed together): https://nodejs.org/⁠
  • Install at least 10.x
  • You should either install it via your package manager or one of the curl | bash scripts they provide: https://nodejs.org/en/download/package-manager/⁠
• You should also install your distro's build tools just in case
  • build-essential for Debian distros, gcc-c++ and make for RHEL distros
• Fork the repository and clone to your computer (not the Pi-hole). In production the Pi-hole only needs the compiled output of the project, not its source
• Open the folder in the terminal
• Run npm install
  • This will install all the packages listed in package.json and will let you build/run the web interface
• Run npm run start-fake to make sure that it is working
  • This will launch the web interface on port 3000 in debug mode
  • If it crashes/has a compile error it will show you the code and the error
  • Changes will be automatically applied and the web interface will reload
• If you've never used React, you should read the React Quick Start⁠ and/or the Tutorial⁠ before diving too deep into the code.
• When you are ready to make changes, make a branch off of development in your fork to work in. When you're ready to make a pull request, base the PR against development.

⁠Testing With Fake Data

• Follow the "Getting Started" guide above
• Checkout the branch you want to test using git checkout
• Run npm install just to make sure you have the correct dependencies for the branch
• Run npm run start-fake to start the web interface with fake data
  • See the npm start-fake section of the getting started guide above for more details, like the port number
• Note: interactive API features, like adding to the whitelist, will not work with fake data

⁠Testing With Real Data

• Follow the "Getting Started" guide above
• Checkout the branch you want to test using git checkout
• Run npm install just to make sure you have the correct dependencies for the branch
• Open package.json and add "proxy": "http://pi.hole". Change the URL to a URL that your API is listening on if it is not http://pi.hole (ex. http://my.device.local:8000)
• Run npm run start to start the web interface
  • See the npm start-fake section of the getting started guide above for more details, like the port number