How to Host a Website on Raspberry Pi 5 with Flask and GPIO

Project Overview & Difficulty Rating

If you want to host a website on a Raspberry Pi, treating it like a standard desktop Linux box is a mistake. The Pi is an embedded controller at heart. In this guide, we aren't just spinning up a static HTML page; we are building an embedded web server that bridges HTTP requests with physical hardware via GPIO. You will deploy a Python Flask application that serves a dashboard while simultaneously monitoring a physical shutdown button and driving a status LED.

Hardware BOM & GPIO Pin Mapping

Before touching the code, we need to wire the physical interface. The Raspberry Pi 5 requires a 5V/5A USB-C PD power supply to negotiate full current; if you use an older 3A brick, the Pi will throttle PCIe and USB currents, which can cause brownouts when the web server spikes under load.

Parts List

• Board: Raspberry Pi 5 8GB
• Power: Official Raspberry Pi 27W USB-C PD Power Supply
• Storage: 64GB Samsung PRO Endurance microSD (or NVMe SSD via Pi 5 PCIe HAT for production)
• Components: 5mm Red LED, 220Ω through-hole resistor, 6x6mm tactile pushbutton, jumper wires, half-size breadboard.

Pin Mapping Table

Step-by-Step: Provisioning the Pi 5 Web Server

Raspberry Pi OS Bookworm enforces PEP 668, meaning you can no longer use pip install globally without breaking system packages. We must use a virtual environment. This is the number one stumbling block for makers migrating from older Bullseye setups.

1. Update the System: Open your terminal and run sudo apt update && sudo apt upgrade -y.
2. Install System Dependencies: The Pi 5 uses the lgpio C library for GPIO access. Install it via apt: sudo apt install python3-lgpio python3-venv.
3. Create Project Directory: mkdir ~/pi-web-server && cd ~/pi-web-server.
4. Initialize Virtual Environment: Run python3 -m venv env --system-site-packages. The --system-site-packages flag is critical; it allows your venv to see the lgpio library we just installed via apt.
5. Activate Environment: source env/bin/activate.
6. Install Flask: pip install flask.

The Code: Flask Server with GPIO Hardware Integration

This script initializes the GPIO pins, sets up a hardware shutdown interrupt, and binds the Flask web server to all network interfaces (0.0.0.0) on port 5000. Save this as app.py in your project directory.

import os
import sys
import threading
from flask import Flask, jsonify
from gpiozero import LED, Button
from signal import pause

app = Flask(__name__)

# --- Pin Definitions ---
STATUS_LED_PIN = 17
SHUTDOWN_BTN_PIN = 27

# Initialize Hardware with Error Handling
try:
    status_led = LED(STATUS_LED_PIN)
    # pull_up=True uses internal resistor; button connects pin to GND when pressed
    shutdown_btn = Button(SHUTDOWN_BTN_PIN, pull_up=True, hold_time=3) 
except Exception as e:
    print(f'FATAL: GPIO Initialization failed. Check wiring and lgpio install.\nError: {e}')
    sys.exit(1)

def hardware_shutdown():
    """Callback triggered when button is held for 3 seconds."""
    print('[SYSTEM] Shutdown button held. Halting system safely...')
    status_led.blink(0.2, 0.2)
    os.system('sudo shutdown -h now')

# Bind hardware event
shutdown_btn.when_held = hardware_shutdown

# --- Web Routes ---
@app.route('/')
def index():
    status_led.on()
    return '<h1>Pi 5 Embedded Web Server</h1><p>System Online. GPIO Active.</p>'

@app.route('/api/status')
def api_status():
    return jsonify({
        'status': 'online',
        'led_state': status_led.is_lit,
        'board': 'Raspberry Pi 5'
    })

if __name__ == '__main__':
    print('[SERVER] Starting Flask on port 5000...')
    status_led.on()
    try:
        # debug=False is mandatory for production; debug=True spawns reloader threads that break gpiozero
        app.run(host='0.0.0.0', port=5000, debug=False)
    except OSError as e:
        if 'Address already in use' in str(e):
            print('FATAL: Port 5000 is bound. A zombie Flask process or another service is using it.')
        else:
            print(f'OS Error binding socket: {e}')
    except KeyboardInterrupt:
        print('\n[SERVER] Shutting down gracefully.')
        status_led.off()
        sys.exit(0)

Debugging: Boot Failures & Socket Errors

When your embedded web server fails, it rarely fails silently. Here are the exact error strings you will encounter and how to fix them.

Error 1: OSError: [Errno 98] Address already in use

Ranked Causes:

1. Zombie Process: You pressed Ctrl+C previously, but the Flask child thread didn't terminate, leaving port 5000 bound in the background.
2. Service Conflict: Another application (like a stray Node.js app or Home Assistant) is already bound to port 5000.

The Fix: Find and kill the process holding the port. Run sudo lsof -i :5000 to find the PID, then sudo kill -9 <PID>. Alternatively, force-kill it with sudo fuser -k 5000/tcp.

Error 2: gpiozero.exc.BadPinFactory: Unable to load any default pin factory!

Ranked Causes:

1. Missing lgpio Backend: You are on Pi 5 / Bookworm, but python3-lgpio is not installed via apt.
2. Venv Isolation: You created your virtual environment without the --system-site-packages flag, hiding the system-level lgpio library from Python.

The Fix: Exit the venv (deactivate), delete the old environment (rm -rf env), and recreate it using python3 -m venv env --system-site-packages. Re-activate and run again.

The First 3 Things to Check When It Fails

Extending and Simplifying the Build

The Flask development server is single-threaded and not meant for heavy production traffic. Depending on your end goal, you should pivot your architecture.

How to Simplify (Static Content Only)

If you don't need Python backend logic or GPIO control and just want to serve static HTML/CSS files, strip out Flask entirely. Navigate to your web root directory and run:

python3 -m http.server 80 --bind 0.0.0.0

This uses Python's built-in HTTP handler. It's lightweight, requires zero dependencies, and is perfect for serving local documentation or basic dashboards.

How to Extend (Production Deployment)

To handle concurrent users and secure the connection, place Gunicorn and Nginx in front of your Flask app.

• Gunicorn: Acts as the WSGI HTTP server, managing multiple worker processes to handle concurrent HTTP requests without blocking your GPIO event loop.
• Nginx: Sits on port 80/443, handles SSL termination (via Let's Encrypt), caches static assets, and reverse-proxies dynamic requests to Gunicorn on localhost:8000.
• Systemd: Wrap your Gunicorn command in a .service file so the web server automatically restarts on boot and recovers from crashes.

Frequently Asked Questions

Can I host a website on a Raspberry Pi without a monitor?

Yes. This is called a 'headless' setup. Flash your Raspberry Pi OS using the official Raspberry Pi Imager on your desktop. Before clicking 'Write', click the gear icon (Advanced Options) to enable SSH, set your username/password, and configure your WiFi SSID. Once booted, you can SSH into the Pi via ssh username@raspberrypi.local to deploy your web server code remotely.

Is it safe to expose my Raspberry Pi website to the public internet?

Directly forwarding port 80/443 via your router's NAT to your Pi's local IP is a security risk; it exposes your home network to automated botnet scanning and DDoS attacks. The modern, secure approach is to use Cloudflare Tunnels (cloudflared). It creates an outbound encrypted tunnel from your Pi to Cloudflare's edge network, allowing public HTTPS access without opening any inbound ports on your home router.

How much traffic can a Raspberry Pi 5 web server handle?

The Pi 5's Broadcom BCM2712 quad-core Cortex-A76 is remarkably capable. When serving static files via Nginx, a Pi 5 can push over 10,000 requests per second on a Gigabit LAN. However, when running dynamic Python/Flask applications with database queries, expect roughly 50 to 150 concurrent requests per second before CPU saturation. For high-traffic dynamic sites, implement Redis caching to offload repetitive database calls.