Installation Guide

"If anything can go wrong, it will go wrong." — Murphy's Law

But with proper preparation, Murphy can take a day off.

Complete guide for installing Pimeleon router on your Raspberry Pi hardware.

Installation Methods

Fresh Installation

For new deployments, see the Fresh Install Guide for step-by-step instructions on:

• Downloading the Pimeleon router image
• Flashing to microSD card with verification
• Initial boot and configuration
• Network setup and testing

System Requirements

Required Hardware

• Raspberry Pi 3B+ or newer (Pi 4 recommended for Gigabit performance)
• 32GB microSD card (Class 10 or UHS-I, high-endurance recommended for reliability)
• Power supply:
  • Pi 3B+: 5V 2.5A (2.5A minimum, 3A recommended)
  • Pi 4: 5V 3A USB-C power supply (official Raspberry Pi adapter highly recommended)
• Ethernet cable for WAN connection to existing router/modem

Optional Hardware

• USB 3.0 Gigabit Ethernet adapter - Add additional LAN port for multi-port configurations
• Case with cooling - Heatsinks or active cooling for sustained performance
• UPS or surge protector - Protect against power fluctuations and ensure clean shutdowns

Software Prerequisites

• Computer for flashing the image (Windows, macOS, or Linux)
• Raspberry Pi Imager or balenaEtcher for writing images
• SSH client (optional, for headless setup)
  • Built into macOS/Linux
  • PuTTY or Windows Terminal on Windows

Pre-Installation Checklist

Before beginning installation, ensure you have:

• Verified hardware compatibility with your Raspberry Pi model
• Downloaded latest stable image from official release page
• Prepared microSD card (32GB minimum, 64GB recommended for extended logging)
• Reviewed network topology to plan integration with existing network
• Backed up existing router settings if replacing current router
• Quality power supply to prevent boot loops and corruption

Quick Start

For users familiar with Raspberry Pi setup:

1. Download Pimeleon router image (.img.xz file)
2. Flash image to microSD card using Raspberry Pi Imager or balenaEtcher
3. Insert microSD card into Raspberry Pi
4. Connect WAN port (primary Ethernet) to existing router/modem
5. Power on device and wait 2-3 minutes for first boot
6. Connect to pimeleon WiFi network or LAN port
7. Access web interface at http://pimeleon.local or 192.168.76.1
8. Complete first-boot setup wizard

Detailed Installation

For comprehensive step-by-step installation, refer to:

• Fresh Installation - Complete first-time setup with image flashing
• Hardware Setup - Physical installation and connection guide
• Network Integration - Integrating into existing network
• First Boot Configuration - Initial system setup and verification

Hardware Setup

Physical Installation Steps

1. Prepare Raspberry Pi:
   • Install heatsinks if included with your case
   • Mount Pi in case (if using)
   • Insert flashed microSD card firmly until it clicks
2. Network Connections:
   • WAN Port (eth0): Connect to your existing router or modem
   • LAN Port (optional): If using USB Ethernet adapter, connect LAN devices
   • WiFi: Built-in WiFi will broadcast pimeleon network after first boot
3. Power Connection:
   • Connect power supply LAST (after all other connections)
   • Power LED (red) should illuminate immediately
   • Activity LED (green) should begin blinking after 5-10 seconds

LED Indicator Guide

Network Integration

Deployment Modes

Mode 1: Gateway Router (Recommended)

• Pimeleon router replaces your existing router
• Modem → Pimeleon router → Network devices
• Full control over DHCP, DNS, firewall, and routing

Mode 2: Transparent Proxy

• Pimeleon router sits between existing router and network
• Router → Pimeleon router → Network devices
• Provides filtering without replacing your router

Mode 3: DNS/DHCP Server Only

• Pimeleon router provides only DNS and DHCP services
• Existing router handles routing and firewall
• Useful for filtering without changing network architecture

First Boot

Initial Access

After first boot (2-3 minutes):

1. Via WiFi:
   • Connect to pimeleon WiFi network
   • Default password: pimeleonrouter
   • Open browser to http://pimeleon.local or 192.168.76.1
2. Via Ethernet:
   • Connect to LAN port (if available) or WAN port temporarily
   • DHCP should assign IP in 192.168.76.x range
   • Open browser to http://192.168.76.1

Setup Wizard

The first-boot wizard guides you through:

1. Admin password creation - Set secure password for web interface
2. Network configuration - Choose deployment mode and IP settings
3. WiFi setup - Configure SSID and password for access point
4. Upstream DNS - Select DNS providers (Cloudflare, Google, Quad9, custom)
5. Basic filtering - Enable DNS filtering and configure blocklists
6. Time zone and locale - Set regional settings

Troubleshooting Installation

Common Issues

Won't Boot / No Green LED

• Check: Power supply provides adequate amperage (2.5A minimum, 3A recommended)
• Check: microSD card is properly seated and not damaged
• Try: Re-flash the image with slower write speed
• Try: Different microSD card (SanDisk Ultra or Samsung EVO recommended)

Can't Access Web Interface

• Check: Device has acquired IP address via DHCP
• Try: Direct URL http://192.168.76.1 instead of hostname
• Try: Clear browser cache or use incognito mode
• Check: Firewall on client computer not blocking access

Network Not Working

• Check: WAN cable connected to correct port (primary Ethernet port)
• Check: Upstream router/modem is functioning
• Try: Reboot both Pimeleon router and upstream router
• Check: DHCP settings don't conflict with upstream network

For detailed troubleshooting, see:

• Boot Issues - LED diagnostics and boot problems
• Network Troubleshooting - Connectivity issues
• Common Problems - General troubleshooting guide

Next Steps

After successful installation:

1. Complete setup wizard with secure passwords and appropriate settings
2. Configure network services:
   • DHCP server settings and static leases
   • DNS configuration and upstream resolvers
   • Firewall rules and port forwarding
3. Enable filtering:
   • DNS filtering with preferred blocklists
   • Optional: Proxy services for privacy
   • Optional: VPN server for remote access
4. Test thoroughly:
   • Verify internet connectivity from client devices
   • Test DNS resolution and ad blocking
   • Confirm expected network performance
5. Create backup of working configuration

Additional Resources

• User Guide - Complete configuration reference
• Network Architecture - Understanding the system design
• Community Forum - Get help from other users
• FAQ - Frequently asked questions