Raspberry-Gateway provides a simple but powerful solution for managing your home internet gateway using a Raspberry Pi. This project includes a range of Docker containers, each serving a specific purpose to enhance your internet experience:
Overall, this Raspberry Pi Home Internet Gateway provides a universal solution for managing and monitoring your home internet enviroment with joy and ease.
Note: You can run it on CM4 board with 8Gb eMMC card. Full installation on top of latest Raspios lite (64bit) will use 4,5Gb of your eMMC card. Raspberry Pi Zero-W or W2 boards can also be used, but it's important to note that they lack an internal Ethernet adapter and have limited CPU and RAM resources. This can restrict the number of containers that can be run and the number of clients that can connect to the VPN server.
Install Ansible:
sudo apt-get install -y git ansible python3-pip musl-tools
Clone this repository:
git clone https://github.com/d3vilh/raspberry-gateway
Then enter the repository directory:
cd raspberry-gateway
Install requirements:
ansible-galaxy collection install -r requirements.yml
Note: If you see
ansible-galaxy: command not found
, you have to relogin (or reboot your Pi) and then try again.Continue Installation with WebUI
Run Webinstall binary:
secret@rpgw:~/raspberry-gateway $ ./webinstall # Supports now both legacy Pi4_x64 and Pi5_x64
2023/07/07 18:01:03 Welcome! The web interface will guide you on installation process.
Installation logs: webinstall.log
2023/07/07 18:01:03 Starting web server on http://10.10.10.18:8088
Copy server address (http://10.10.10.18:8088
as above example) from the console and paste into your browser, then press Enter. Raspberry-Gateway webinstall window will appear:
Choose all the components you would like to install and change all the passwords (keep them in mind).
Note: You can leave all the passwords as default, but it's not recommended.
Press "Save" button. When your configuration is ready:
Then press "Install" button. It will initiate installation in background:
The installation process will take some time. Once that's done, it'll be like you have a new Raspberry Gateway up and running.
Uninstall "component"
checkbox then save
configuration file and press Uninstall
button.webinstall
run - modify example.config.yml
with the default parameters. ansible_user
can be set in example.inventory.yml
file.
Afraid of GUI? Need more control?
Make copies of the configuration files and modify them for your enviroment:
yes | cp -p example.inventory.yml inventory.yml
yes | cp -p example.config.yml config.yml
Double check that ansible_user
is correct for inventory.yml
. Need to run installtion on the remote server - follow the recomendations in config file.
Note: To make all necesary changes:
nano inventory.yml
, save the file -Ctrl+O
andCtrl+X
to exit.
Modify config.yml
to enable or disable desired containers to be installed on your Pi.
For example, to enable Portainer - change enable_portainer: false
option to enable_portainer: true
and vs to disable.
Note: Default configuration options in the list below are bold.
List of available configuration options
Portainer
portainer_enable: true
or false
- to install Portainer, the Web-ui for Docker. Default true.remove_portainer: true
or false
- to uninstall Portainer. Default false.Unbound DNS
unbound_dns_enable: true
or false
- to install Unbound DNS, the fast and lean DNS. Default true. Beaware that Unbound DNS is not compatible with Techtitium DNS as they both use port 53.remove_unbound_dns: true
or false
- to uninstall Unbound DNS. Default false.additional parameters
- in config.yml
you'll see lot of additional parameters with default values. You can change them if you know what you are doing. Short description of each parameter is available in the same file.Pi-Hole
pihole_enable: true
or false
- to install Pi-Hole. Default true. Beaware that Pi-Hole is not compatible with Technitium DNS as they both use port 53.remove_pihole: false
or true
- to uninstall Pi-Hole. Default false.pihole_inside_vpn: false
or true
- configure Pi-Hole to use your OpenVPN Client subnet instead of public Internet.pihole_password
- password for Pi-Hole WEB UI. Default "gagaZush".Technitium DNS
tech_dns_enable: false
or true
- to install Technitium DNS. Default false. Beaware that Technitium DNS is not compatible with Pi-Hole and Unbound DNS as they use port 53 as well.remove_tech_dns: false
or true
- to uninstall Technitium DNS. Default false.tech_dns_password
- password for Technitium DNS WEB UI. Default "gagaZush".tech_dns_inside_vpn: false
or true
- configure Technitium DNS to use your OpenVPN Client subnet instead of public Internet.additional parameters
- in config.yml
you'll see lot of additional parameters with default values. You can change them if you know what you are doing. Short description of each parameter is available in the same file.OpenVPN Server Advanced OpenVPN Server documentation and configuration examples is here.
ovpn_server_enable: false
or true
- to install OpenVPN Server. Default false.remove_ovpn_server: false
or true
- to uninstall OpenVPN Server. Default false.ovpnui_user
- username for OpenVPN WEB UI. Default "admin".ovpnui_password
- password for OpenVPN WEB UI. Default "gagaZush".additional parameters
- in config.yml
you'll see lot of additional parameters with default values. You can change them if you know what you are doing. Short description of each parameter is available in the same file.OpenVPN Client Advanced OpenVPN Client documentation with configuration examples is here.
ovpn_client_enable: false
or true
- to install OpenVPN Client. Default false.remove_ovpn_client: false
or true
- to uninstall OpenVPN Client. Default false.*.ovpn
into openvpn-client
directory before installation and update its name in ovpn_client_cert: "your-client.ovpn"
option before installation. Default "webinstall-client.ovpn".ovpn_client_secret: "file with client secrets"
- filename with your OpenVPN connection profile user and password if you have any. Default "webinstall-credentials.txt".ovpn_client_allowed_subnet: "your home wifi subnet/mask"
- your local subnet from which you want to access qBitTorrent web-ui when VPN Client connection is active. Default "192.168.88.0/24".ovpn_client_killswitch: false
or true
- block all traffic if ovpn-client is down. Default true.Gluetun
gluetun_vpnclient_enable: false
or true
- to install Gluetun VPN Client. Default false.remove_gluetun_vpnclient: false
or true
- to uninstall Gluetun VPN Client. Default false.additional parameters
- in config.yml
you'll see lot of additional parameters with default values. You can change them if you know what you are doing. Short description of each parameter is available in the same file.WireGuard Server
wireguard_server_enable: false
or true
- to install WireGuard Server. Default false.remove_wireguard: false
or true
- to uninstall WireGuard Server. Default false.wireguard_password
- password for WireGuard WEB UI. Default "gagaZush".wireguard_user
- username for WireGuard WEB UI. Default "admin".wireguard_serverurl
- URL for WireGuard WEB UI. Default "wg.example.com".qBitTorrent
qbittorrent_enable: false
or true
- to install qBitTorrent. Default false.remove_qbittorrent: false
or true
- to uninstall qBitTorrent. Default false.qbittorrent_inside_vpn: false
or true
- configure qBittorrent to use your OpenVPN Client subnet instead of public Internet. Dont forget to endable OpenVPN Client installation as well.qbittorrent_inside_gluetun: false
or true
- configure qBittorrent to use your Gluetun VPN Client subnet instead of public Internet. Dont forget to endable Gluetun installation as well.qbittorrent_webui_port: "8090"
- qBittorrent WEB UI port. Keept is default "8090".Raspberry Monitoring Advanced Raspberry Monitoring documentation is here.
monitoring_enable: true
or false
- to install Raspberry Monitoring. Default true.remove_monitoring: false
or true
- to uninstall Raspberry Monitoring. Default false.monitoring_grafana_admin_password
- password for Grafana WEB UI. Default "gagaZush".monitoring_days_keep_interval: "90d"
- how long to keep data in Prometheus DB. Default "90d".monitoring_speedtest_interval: "1h"
- how often to run speedtest. Default "60m".monitoring_ping_interval: "1m"
- how often to run ping tests. Default "30s".openvpn_monitoring_enable: true
or false
- install OpenVPN monitoring dashboard. Default false.remove_openvpn_monitoring: false
or true
- to uninstall OpenVPN monitoring dashboard. Default false.pikvm_monitoring_enable: true
or false
- install Pi-KVM monitoring dashboard. Default false.remove_pikvm_monitoring: false
or true
- to uninstall Pi-KVM monitoring dashboard. Default false.pikvm_target_ip: "PiKVM IP"
- Pi-KVM IP address to gather statistics from. Default "192.168.88.3".pikvm_web_user: "admin"
- Pi-KVM side preconfigured Web-UI username. Default "admin".pikvm_web_password
- Pi-KVM side preconfigured Web-UI password. Default "gagaZush".airgradient_monitoring_enable: true
or false
- install AirGradient monitoring dashboard. Default false.remove_airgradient_monitoring: false
or true
- to uninstall AirGradient monitoring dashboard. Default false.
Complete your AirGradient monitoring configuration in advanced.config.yml
.starlink_monitoring_enable: true
or false
- install StarLink monitoring dashboard. Default false.remove_starlink_monitoring: false
or true
- to uninstall StarLink monitoring dashboard. Default false.starlink_ip: "StarLink IP"
- StarLink IP address to get statistics from. Default "10.10.10.1".starlink_port: "9817"
- StarLink port to get statistics from. Default "9817".shellyplug_monitoring_enable: true
or false
- install ShellyPlug monitoring dashboard. Default false.remove_shelly_plug_monitoring: false
or true
- to uninstall ShellyPlug monitoring dashboard. Default false.shelly_plug_hostname: "ShellyPlug IP"
- ShellyPlug IP address or hostname to get statistics from. Default "server-room-shelly"shelly_ip: "ShellyPlug IP"
- ShellyPlug IP address to get statistics from. Default "192.168.88.66".shelly_port: "ShellyPlug Port"
- ShellyPlug port to get statistics from. Default "9924".shelly_plug_http_username
- ShellyPlug HTTP username. Default "admin".shelly_plug_http_password
- ShellyPlug HTTP password. Default "gagaZush".Xray Server Advanced Xray Server documentation and configuration examples is here.
xray_enable: false
or true
- to install XRAY Server. Default false.remove_xray: false
or true
- to uninstall XRAY Server. Default false.
Modify advanced configuration options in advanced.config.yml
if you desire to use additional Monitoring features, such as Telegram bot for notifications, to share your Grafana dashboard over Internet, to tune hosts to ping or set AirGradient monitoring parameters.
Run installation playbook:
ansible-playbook main.yml
Note: If running locally on the Pi: You may have error like
Error while fetching server API version
. You have to relogin to your Pi and then run the playbook again.
Pi-hole or Technitium-dns as the network-wide ad-blocking solution integrated with own local DNS and DHCP servers:
OpenVPN Server with subnets support and openvpn-ui as fast and lightweight web administration interface or WireGuard server - an extremely simple yet fast and modern VPN with own web administration interface:
OpenVPN Client container for using external OpenVPN server connection for selected containers of this project.
Note: qBitTorrent can be configured to use OpenVPN Client or Gluetun connection to download torrents the way your ISP will not recognize!
GlueTun container as universal VPN client for using with multiple commercial VPN providers and built-in DNS over TLS, with a few proxy servers.
Xray Server container, with experimental Shadowsocks and XTLS-Reality fast tunnel proxy that helps you to bypass firewalls.
qBittorrent an open-source software alternative to µTorrent, with lightweight web administration interface:
Portainer is a lightweight universal management interface that can be used to easily manage containers and environment which included in this setup:
Raspi Monitoring The simple yet powerfull monitoring solution for your Raspberry Gateway. Covers performance utilisation (CPU,MEM,I/O, storage usage), Hardware utilisation (Temperature, Voltage, Power States, Devices Clock), Docker containers statistics and Internet connection monitoring:
AirGradient Monitoring: Accurate and Open Air Quality Monitoring Dashboard:
UI access port http://localhost:9000/
(change localhost
to your Raspberry host ip/name)
Default password will be set during the first login
External ports used by container: 9000:tcp
, 8000:tcp
(external API)
UI access port http://localhost:80/
(change localhost
to your Raspberry host ip/name)
Default password is gagaZush
it is preconfigured in config.yml
file in pihole_password
var
Unbound DNS connection can be enabled in the config.yml
. Default option - pihole_with_unbound: true
External ports used by container: 80:tcp
, 443:tcp
, 53:tcp
, 53:udp
, 67:tcp
, 67:udp
Note: If you would like to add Unbound functionality to Pi-Hole, you have to stop and remove old Pi-Hole setup and re-install it again.
UI access port no UI available, running in Back-End.
Default password password is not required.
Pi-Hole pair to disable, you have to set pihole_with_unbound: false
in config.yml
before the installation.
External ports used by container: 5335:tcp
, 5335:udp
Configuration file is available after the installation and located in ~/unbound-dns/etc-unbound/unbound.conf
Note: If you would like to add Unbound to the existent Pi-Hole setup, you have to stop and remove old Pi-Hole container and re-install it again alltogeather with Unbound and necessary options enabled.
UI access port http://localhost:5380/
, (change localhost
to your Raspberry host ip/name)
Default password is gagaZush
it is preconfigured in config.yml
file in the tech_dns_password
var
External ports used by container: 5380:tcp
, 53:tcp
, 53:udp
Configuration files are available after the installation and located in ~/tech-dns/config/
directory
UI access port http://localhost:8090/
, (change localhost
to your Raspberry host ip/name)
Default password is admin/adminadmin
, which must be changed via web interface on first login.
External ports used by container: 8090:tcp
, 6881:tcp
, 6881:udp
Configuration files are available after the installation and located in ~/qbittorrent/config/qBittorrent/
directory
Downloaded files will be stored in the ~/qbittorrent/downloads
directory.
Note: To prove you are connected via VPN run this command
sudo docker exec qbittorrent wget -qO - ifconfig.me
it should return your VPN IP address.
UI access port http://localhost:8080/
, (change localhost
to your Raspberry host ip/name)
Default password is gagaZush
it is preconfigured in config.yml
file in the ovpnui_password
var
External ports used by containers, by default: 8080:tcp
, 1194:tcp
, 1194:udp
Configuration files are available after the installation and located in ~/openvpn-server/*
directory
All the OpenVPN Server configuration and Knowhow for this setup can be found here.
Note: If you are looking for x86_64 version of OpenVPN and openvpn-ui containers, please check openvpn-aws
UI access port no UI available, running in Back-End
Default password password is not required
External ports used by container, by default: random free port
Configuration files are available after the installation and located in ~/openvpn-client/*
directory.
Configuration Options necessary for the installation (defined in config.yml
file)`):
ovpn_client_cert: "example-client.opvn"
- file with your OpenVPN connection profile (*.ovpn
). You have to put it into ~/raspberry-gateway/openvpn-client/
directory before installation and update its name in ovpn_client_cert
. Use the example-client.ovpn as a refference of all necessary options and file format. After the installation your *.ovpn
file will be moved to ~/openvpn-client/*.ovpn
and used by container. If for some reason you need to change it, you have to put new file with the same name in ~/openvpn-client/
directory and restart openvpn-client container (docker openvpn-client restart
).ovpn_client_allowed_subnet: "192.168.88.0/24"
- Your local newtwork (WiFi or whatever), from which you want to access qBitTorrent WEB-UI when VPN Client connection is active.
Note: To prove you are connected via VPN run this command
sudo docker exec openvpn-client wget -qO - ifconfig.me
it should return your VPN IP address.
For more documentation and How-to, please check dedicated openvpn-client README.md file.
Note: If you just looking for all purpose OpenVPN client for Raspberry-Pi or x86 PC, please check vpntv project.
UI access port no UI available, running in Back-End
Default password password is not required
External ports 8888/tcp
as HTTP proxy, 8388/tcp
&8388/udp
for Shadowsocks
Configuration files are available after the installation and located in ~/openvpn-client/*
directory.
Configuration Options which necessary for the installation (defined in config.yml
file)`):
gluetun_vpn_service_provider
- is your VPN service provider (expressvpn, ivpn, nordvpn, protonvpn, surfshark, etc.) full list of supported providers available here. gluetun_openvpn_user
- is your OpenVPN user provided by VPN providergluetun_openvpn_password
- is your OpenVPN password, provided by VPN providergluetun_server_countries
- is comma separated list of countriesgluetun_server_update_per
- is period to update your servers list using the built-in Gluetun update mechanisms (curently hardcoded to 24h)UI access port http://localhost:5000/
, (change localhost
to your Raspberry host ip/name)
Default password is gagaZush
it is preconfigured in config.yml
file in the wireguard_password
var
External ports used by container: 5000:tcp
, 6881:tcp
, 6881:udp
Configuration files are available after the installation and located in ~/tech-dns/config/
directory
Main Documentation and Configuration examples is here.
UI access port http://localhost:54321
, (change localhost
to your Raspberry host ip/name)
Default password is admin/admin
, which must be changed via web interface on first login (Pannel Settings
> User Settings
).
External ports used by container: 443:tcp
, 80:tcp
, 54321:tcp
(by default)
Configuration files are available after the installation and located in ~/xray/
directory
It is Important to change following settings for better security:
Pannel Settings
> User Settings
> Password
to something strong and secure.Pannel Settings
> Pannel Configurations
> Pannel Port
from 54321
to some random port (the best in the upper end of the range, up to 65535
)Pannel Settings
> Pannel Configurations
> Panel URL Root Path
to something random, like /mysecretpannel/
or /superxray/
.All the Data sources, Dashboards and exporters are automatically provisioned. Below you can find the list of available dashboards and their URLs.
Used to visualize all the data provided by Prometheus.
UI access port http://localhost:3030/
, (change localhost
to your Raspberry host ip/name)
Default password is admin/admin
, it is preconfigured in config.yml
file and only used the first time Grafana starts up
External ports used by container: 3030:tcp
Configuration files are available after the installation and located in ~/monitoring/grafana/
directory
Advanced Configuration Before the installation, can be predefined in advanced.config.yml
.
Raspberry Pi Monitoring: Shows CPU, memory, and disk usage, as well as network traffic, temperature and Docker containers utilisation. http://localhost:3030/d/rvk35ERRz/raspberry-monitoring
OpenVPN Monitoring: - OpenVPN activity dashboard. http://localhost:3030/d/58l7kyvVz/openvpn
AirGradient Monitoring - Air quality dashboard. http://localhost:3030/d/aglivingroom/airquality-airgradient
Note 1: You have to configure your AirGradient device in
advanced.config.yml
before the installation. Note 2: Your AirGradient device must have alternative airgradient-improved firmware flashed into EEPROM to support this feature.
Starlink Monitoring: Starlink monitoring dashboard. http://localhost:3030/d/GG3mnflGz/starlink-overview
Shelly Plug Monitoring: Shelly Plug dashboard. http://localhost:3030/d/i_aeo-uMz/power-consumption
Note: Change
localhost
to your Raspberry ip/hostname.
If you don't see any data on the dashboard - try to change the time duration to something smaller. If this does not help - check via Portainer UI that all the exporters and containers are running:
Then debug Prometheus targets described in the next partagraph.
Used for metrics collection from exporters, storing data and provide it to Grafana dashboards.
UI access port http://localhost:9090/
, (change localhost
to your Raspberry host ip/name)
Default password password is not set by default!
External ports used by container: 9090:tcp
, various exporters ports (see below)
Configuration files are available after the installation and located in ~/monitoring/prometeus/
directory
Targets can be checked on http://localhost:9090/targets
(you know what2do with localhost
🧐)
Node exporter - Standard Linux server monitoring (CPU,RAM,I/O,FS,PROC). http://nodeexp:9100/metrics
cAdvisor exporter - Docker containers monitoring. http://cadvisor:8080/metrics
rpi_exporter - RaspberryPI HW monitoring. http://rpi_exporter:9110/metrics
Speedtest exporter - Up/down speed and latency. http://speedtest:9798/metrics
Blackbox exporter - Desired sites avilability. http://ping:9115/probe
OpenVPN exporter - OpenVPN activity monitoring. http://ovpn_exporter:9176/metrics
AirGradient exporter - AirQuality monitoring. http://remote-AirGradient-ip:9926/metrics
PiKVM exporter - PiKVM utilisation and temp monitoring. https://remote-PiKVM-ip/api/export/prometheus/metrics
Starlink exporter - Starlink monitoring. http://starlink:9817/metrics
Shelly exporter - Shelly Plug power consumption monitoring. http://shelly:9924/metrics
May 2021, d3vilh