$ cat installation.md

INSTALLATION_GUIDE

Complete installation instructions for Pi VPN Hotspot. This guide covers everything from initial setup to advanced configuration.

§ SYSTEM_REQUIREMENTS

HARDWARE

  • →Raspberry Pi 3B+ or newer
  • →4GB RAM (minimum 2GB)
  • →MicroSD card 16GB+ (Class 10)
  • →Power supply (5V 3A recommended)
  • →WiFi adapter (built-in or USB)

SOFTWARE

  • →Raspberry Pi OS (Bullseye/Bookworm)
  • →WireGuard VPN subscription
  • →SSH access enabled
  • →Internet connection
  • →Android device (optional, for SMS)

§ PREPARATION

1. Flash Raspberry Pi OS

Use Raspberry Pi Imager to flash the latest Raspberry Pi OS to your microSD card.

# Download from:
https://www.raspberrypi.com/software/

# Enable SSH during imaging:
Advanced Options → Enable SSH

2. Initial Boot and Update

Boot your Pi and perform initial system updates.

$ sudo apt update
$ sudo apt upgrade -y
$ sudo apt install git curl wget -y

3. Obtain WireGuard Configuration

Get your WireGuard configuration file from your VPN provider.

Most VPN providers offer WireGuard configs in their account dashboard. Download the .conf file for your server location.

§ INSTALLATION_PROCESS

STEP_01|Download Package
$ cd ~
$ wget https://github.com/your-repo/pi-vpn-hotspot/archive/main.tar.gz
$ tar -xzf main.tar.gz
$ cd pi-vpn-hotspot-main
STEP_02|Install Dependencies
$ sudo apt install wireguard hostapd dnsmasq iptables-persistent -y
$ sudo systemctl stop hostapd
$ sudo systemctl stop dnsmasq

This installs WireGuard VPN, hostapd (for hotspot), dnsmasq (for DHCP), and iptables for firewall rules.

STEP_03|Configure WireGuard
# Copy your WireGuard config
$ sudo cp /path/to/your/wg0.conf /etc/wireguard/
$ sudo chmod 600 /etc/wireguard/wg0.conf

# Test VPN connection
$ sudo wg-quick up wg0
$ curl ifconfig.me
$ sudo wg-quick down wg0
STEP_04|Configure Hotspot
# Edit hostapd configuration
$ sudo nano /etc/hostapd/hostapd.conf

# Add these settings:
interface=wlan0
driver=nl80211
ssid=YourHotspotName
hw_mode=g
channel=7
wmm_enabled=0
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wpa=2
wpa_passphrase=YourSecurePassword
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP
rsn_pairwise=CCMP
STEP_05|Configure DHCP
$ sudo nano /etc/dnsmasq.conf

# Add these lines:
interface=wlan0
dhcp-range=192.168.4.2,192.168.4.20,255.255.255.0,24h
domain=wlan
address=/gw.wlan/192.168.4.1
STEP_06|Run Installation Script
$ sudo chmod +x install.sh
$ sudo ./install.sh

The installation script will configure networking, set up the kill switch, and enable all services. Your Pi will reboot when complete.

§ POST_INSTALLATION

Verify Services

# Check all services
$ sudo systemctl status wg-quick@wg0
$ sudo systemctl status hostapd
$ sudo systemctl status dnsmasq

# Verify VPN connection
$ sudo wg show
$ curl ifconfig.me

Test Kill Switch

# Disconnect VPN and test
$ sudo wg-quick down wg0
$ ping 8.8.8.8
# Should fail - kill switch working

$ sudo wg-quick up wg0
$ ping 8.8.8.8
# Should succeed - VPN active

Access Web Dashboard

Connect a device to your hotspot and navigate to the dashboard:

http://192.168.4.1:8080

§ TROUBLESHOOTING

VPN won't connect

Check WireGuard configuration and firewall rules:

$ sudo wg show
$ sudo journalctl -u wg-quick@wg0

Hotspot not visible

Verify hostapd is running and wlan0 is configured:

$ sudo systemctl status hostapd
$ iwconfig wlan0

No internet on connected devices

Check IP forwarding and NAT rules:

$ cat /proc/sys/net/ipv4/ip_forward
$ sudo iptables -t nat -L

INSTALLATION_COMPLETE

Your Pi VPN Hotspot is now fully configured and operational. All traffic from connected devices will be routed through your VPN with kill switch protection.

→ Next: Read the User Guide for advanced features and SMS control setup