Hosting a Website from Raspberry Pi: Flask & GPIO Control Guide

If you are hosting a website from Raspberry Pi hardware, you are likely bridging the gap between physical electronics and network-accessible interfaces. While you can serve static HTML via Nginx, the real power of the Pi lies in dynamic, hardware-aware web servers. This guide walks through building a Python Flask web server that reads and writes to the Pi's GPIO pins, allowing you to control physical components from any browser on your LAN.

The direct answer: To host an interactive hardware website on a Pi, use Python Flask paired with the gpiozero library, running inside a Python virtual environment on Raspberry Pi OS (Bookworm or later). Bind the server to 0.0.0.0 on port 5000 for LAN access, and manage port 80 routing via a reverse proxy if public exposure is required.

Project Overview & Hardware Requirements

Difficulty: Intermediate | Time: 45 Minutes | Target Board: Raspberry Pi 4 Model B (4GB) or Raspberry Pi 5

The Raspberry Pi 4 Model B (4GB variant, ~$55) remains the benchmark for this build due to its native gigabit Ethernet and mature thermal profile. If you are using the Raspberry Pi 5 ($60+), note that it requires a dedicated 27W USB-C PD power supply to prevent brownouts when driving GPIO loads and the CPU simultaneously.

Parts List

Microcontroller: Raspberry Pi 4 Model B (4GB RAM) or Raspberry Pi 5
Storage: SanDisk Extreme 32GB microSD (A1 rated for minimum I/O latency)
Power: Official Raspberry Pi 27W USB-C Power Supply (for Pi 5) or 15W (for Pi 4)
Components: 1x 5mm Red LED, 1x 270Ω through-hole resistor, 1x 12mm tactile push button
Wiring: Half-size breadboard, male-to-female jumper wires

Wiring the GPIO Status & Control Interface

Before writing code, we must map the physical pins. We are using gpiozero, which defaults to the Broadcom (BCM) pin numbering scheme, not the physical board pin numbers.

Component	BCM GPIO Pin	Physical Pin	Wiring Notes
LED Anode (+)	GPIO 17	Pin 11	Connect in series with 270Ω resistor
LED Cathode (-)	GND	Pin 9	Common ground rail
Button Switch 1	GPIO 27	Pin 13	Software pull-up enabled (no external resistor needed)
Button Switch 2	GND	Pin 14	Common ground rail

Bench Tip: Never wire an LED directly from a 3.3V GPIO pin to ground without a current-limiting resistor. A standard 5mm LED draws ~20mA; the Pi's GPIO pins are rated for a maximum of 16mA per pin and 50mA total across all banks. The 270Ω resistor limits current to ~12mA, keeping you safely within spec.

Setting Up the Flask Web Server Environment

Raspberry Pi OS Bookworm enforces PEP 668, which prevents you from installing Python packages globally via pip to protect system dependencies. You must use a virtual environment.

Update the OS and install base packages:
sudo apt update && sudo apt upgrade -y
sudo apt install python3-venv python3-pip ufw -y
Create and activate the virtual environment:
mkdir ~/pi-web-server && cd ~/pi-web-server
python3 -m venv venv
source venv/bin/activate
Install Flask and dependencies:
pip install flask
Note: gpiozero and lgpio (the backend pin factory for Bookworm) are pre-installed in the Pi OS system Python, but to use them inside a venv, you must recreate the venv with system site packages: python3 -m venv --system-site-packages venv.
Configure the Firewall (UFW):
sudo ufw allow 5000/tcp
sudo ufw enable

The Python Code: Routing, GPIO, and Error Handling

Save the following code as app.py inside your ~/pi-web-server directory. This script initializes the hardware, defines the HTML template inline (to avoid external file dependencies for this tutorial), and includes explicit error handling for network and hardware faults.

import os
import sys
from flask import Flask, render_template_string, request
from gpiozero import LED, Button

# --- Pin Definitions (BCM Numbering) ---
LED_PIN = 17
BUTTON_PIN = 27

# --- Hardware Initialization ---
# pull_up=True uses the Pi's internal 3.3V pull-up resistor.
# Pressing the button connects it to GND, pulling the state LOW (False).
led = LED(LED_PIN)
button = Button(BUTTON_PIN, pull_up=True, bounce_time=0.1)

app = Flask(__name__)

HTML_TEMPLATE = '''
<!DOCTYPE html>
<html>
<head>
    <title>Pi GPIO Control</title>
    <style>
        body { font-family: sans-serif; max-width: 600px; margin: 40px auto; }
        .status { padding: 10px; border-radius: 5px; margin: 10px 0; }
        .on { background-color: #d4edda; color: #155724; }
        .off { background-color: #f8d7da; color: #721c24; }
        button { padding: 10px 20px; font-size: 16px; cursor: pointer; }
    </style>
</head>
<body>
    <h1>Raspberry Pi Hardware Server</h1>
    <div class='status {{ led_class }}'>LED Status: {{ led_status }}</div>
    <div class='status'>Button Status: {{ btn_status }}</div>
    <form method='POST' action='/toggle'>
        <button type='submit'>Toggle LED</button>
    </form>
</body>
</html>
'''

@app.route('/')
def index():
    led_status = 'ON' if led.is_lit else 'OFF'
    led_class = 'on' if led.is_lit else 'off'
    btn_status = 'PRESSED' if button.is_pressed else 'RELEASED'
    return render_template_string(HTML_TEMPLATE, 
                                  led_status=led_status, 
                                  led_class=led_class,
                                  btn_status=btn_status)

@app.route('/toggle', methods=['POST'])
def toggle():
    led.toggle()
    return index()

if __name__ == '__main__':
    try:
        # Bind to 0.0.0.0 to accept connections from any LAN device
        # Port 5000 avoids the need for root privileges (port 80 requires sudo)
        print('Starting Flask server on http://0.0.0.0:5000')
        app.run(host='0.0.0.0', port=5000, debug=False)
    except PermissionError as e:
        print(f'Permission Error: {e}. Are you trying to bind to port 80 without sudo?')
        sys.exit(1)
    except OSError as e:
        print(f'OS Error: {e}. Port 5000 is likely in use. Run: lsof -i :5000')
        sys.exit(1)
    finally:
        print('Shutting down and cleaning up GPIO resources...')
        led.close()
        button.close()

Run the server with python3 app.py. Open a browser on your PC and navigate to http://<your-pi-ip>:5000.

Debugging: Exact Errors and Ranked Causes

When hosting a website from Raspberry Pi boards, network and permission errors are the most common points of failure. If the server crashes or refuses connections, here are the first three things to check:

Port Conflicts: Is another process holding port 5000?
Firewall Rules: Did UFW actually allow the port?
Virtual Environment State: Are you running the script inside the activated venv with --system-site-packages?

Exact Error Strings and Fixes

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

Cause A (Most Likely): You hit Ctrl+C improperly, or a previous instance of the Flask app is hanging in the background as a zombie process.
Cause B: Another service (like a leftover Docker container or default Pi software) is bound to 5000.
Fix: Run lsof -i :5000 to find the PID, then kill -9 <PID>. Alternatively, change the port in the Python code to 5001.

Error 2: PermissionError: [Errno 13] Permission denied

Cause: You changed the port in the code to 80 to avoid typing :5000 in the browser, but you are running the script as a standard user (pi or your custom username). Linux restricts ports below 1024 to the root user.
Fix: Do not run Flask with sudo. Instead, use sudo setcap 'cap_net_bind_service=+ep' /usr/bin/python3.11 to grant Python permission to bind low ports, or keep port 5000 and use an Nginx reverse proxy to map port 80 to 5000.

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

Cause: You created your virtual environment without the --system-site-packages flag, meaning gpiozero cannot see the underlying lgpio C-extension required to talk to the Pi's hardware registers in Bookworm OS.
Fix: Delete the venv folder and recreate it using python3 -m venv --system-site-packages venv.

Deploying as a Service & Extending the Build

Running python3 app.py in a terminal is fine for debugging, but a production server must survive reboots and SSH disconnects. We use systemd to daemonize the process.

Create a service file: sudo nano /etc/systemd/system/piweb.service
Paste the following configuration (adjust paths and usernames):

[Unit]
Description=Raspberry Pi Flask GPIO Server
After=network.target

[Service]
User=pi
WorkingDirectory=/home/pi/pi-web-server
Environment='PATH=/home/pi/pi-web-server/venv/bin'
ExecStart=/home/pi/pi-web-server/venv/bin/python3 app.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start: sudo systemctl enable piweb && sudo systemctl start piweb
Verify status: systemctl status piweb

How to Extend or Simplify the Build

Simplify: If you don't need hardware control and just want to host static files (HTML/CSS/JS), drop Flask entirely. Install Nginx (sudo apt install nginx) and drop your files into /var/www/html. It uses a fraction of the RAM and handles thousands of concurrent requests.
Extend: For production web apps, Flask's built-in Werkzeug server is not designed for heavy concurrent traffic. Extend this build by installing Gunicorn (pip install gunicorn) to handle the Python processing, and place Nginx in front of it as a reverse proxy to handle SSL termination (via Let's Encrypt) and static asset caching.

Frequently Asked Questions

Can I host a public-facing website from Raspberry Pi using Cloudflare Tunnels?

Yes, and it is the most secure method for doing so. Instead of opening port 80/443 on your home router and exposing your Pi's IP address to the open internet, you install cloudflared on the Pi. It creates an outbound-only tunnel to Cloudflare's edge network. You map your domain to the tunnel, and Cloudflare routes incoming traffic securely to your local localhost:5000 Flask instance without any router port forwarding.

Is hosting a website from Raspberry Pi secure enough for production?

For personal dashboards, home automation, or internal LAN tools, yes. For commercial production, no. The Pi lacks hardware-level security enclaves (like TPMs found on enterprise servers) and relies on microSD cards, which are prone to I/O corruption under heavy database write loads. If you must use a Pi in production, boot from an external USB SSD and ensure your Flask app uses parameterized queries to prevent SQL injection.

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

Using Flask's built-in development server (as shown in this guide), a Pi 4 Model B can handle roughly 50 to 100 concurrent requests per second for simple GPIO-toggle pages before latency spikes above 500ms. If you switch to Gunicorn with 4 worker processes and serve a cached static frontend via Nginx, the Pi 4 can comfortably push 1,500+ requests per second over its gigabit Ethernet interface.