How to Host a Website on Raspberry Pi 5: Nginx, Flask, and GPIO Control

The Verdict: Best Hardware and Software Stack to Host a Website on Raspberry Pi

If you want to host a website on Raspberry Pi that can also interact with physical hardware, the optimal stack is a Raspberry Pi 5 (4GB) running Raspberry Pi OS Lite (64-bit), using Nginx as a reverse proxy and Gunicorn + Python Flask as the application server.

Hosting directly from a development server (like Flask's built-in Werkzeug) is a security and performance risk. Nginx handles static assets, SSL termination, and concurrent connection buffering, while Gunicorn manages Python worker processes. This combination uses roughly 180MB of RAM at idle, leaving plenty of headroom for sensor polling and database operations.

Parts List and GPIO Pin Mapping

To build this physical web server, you need components that can handle continuous 24/7 operation without thermal throttling or SD card corruption. Total build cost is approximately $85.

• Compute: Raspberry Pi 5 (4GB RAM variant) - $60
• Power: Official Raspberry Pi 27W USB-C PD Power Supply - $12 (Do not use a generic phone charger; the Pi 5 will throttle USB current to 600mA without PD negotiation).
• Storage: Samsung EVO Plus 64GB microSD (A2 rating) - $13 (A2 rating is critical for random I/O operations from database writes).
• Indicators: 5mm Red LED, 330Ω resistor, tactile pushbutton.

Step-by-Step: Configuring Nginx and Flask on Pi OS Lite

1. Update the system and install core packages:
   sudo apt update && sudo apt upgrade -y
sudo apt install nginx python3-venv python3-pip -y
2. Create the application directory and virtual environment:
   mkdir ~/pi_webserver && cd ~/pi_webserver
python3 -m venv venv
source venv/bin/activate
3. Install Python dependencies:
   pip install flask gunicorn gpiozero
   Note: Raspberry Pi OS Bookworm uses the lgpio backend for gpiozero by default, avoiding the deprecated RPi.GPIO library.
4. Configure Nginx as a reverse proxy:
   Create a new site config: sudo nano /etc/nginx/sites-available/pi_webserver
   Paste the following block to route traffic to Gunicorn on port 5000:

   server {
       listen 80;
       server_name _;
       location / {
           proxy_pass http://127.0.0.1:5000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }

5. Enable the site and restart Nginx:
   sudo ln -s /etc/nginx/sites-available/pi_webserver /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default
sudo systemctl restart nginx
6. Create a systemd service for Gunicorn:
   Create sudo nano /etc/systemd/system/gunicorn.service to ensure the app runs on boot and restarts on failure. Set User=admin and WorkingDirectory=/home/admin/pi_webserver. The ExecStart command should be /home/admin/pi_webserver/venv/bin/gunicorn -w 3 -b 127.0.0.1:5000 app:app.

Complete Python Flask Code with GPIO Integration

Save the following code as app.py in your ~/pi_webserver directory. This script targets the Raspberry Pi 5 (4GB) and uses the BCM pin numbering scheme defined in the hardware table above. It includes explicit error handling for port binding and GPIO initialization failures.

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

# Initialize Flask app
app = Flask(__name__)

# Configure logging
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

# ==========================================
# PIN DEFINITIONS (BCM Numbering)
# ==========================================
LED_PIN = 17       # Physical Pin 11
BUTTON_PIN = 27    # Physical Pin 13

# Hardware Initialization with Error Handling
try:
    status_led = LED(LED_PIN)
    reset_button = Button(BUTTON_PIN, pull_up=True, bounce_time=0.05)
    logging.info(f"GPIO initialized successfully: LED on {LED_PIN}, Button on {BUTTON_PIN}")
except Exception as e:
    logging.critical(f"Failed to initialize GPIO. Check pin mappings and permissions. Error: {e}")
    sys.exit(1)

def hardware_reset_action():
    logging.warning("Hardware button pressed. Toggling LED and logging event.")
    status_led.blink(on_time=0.2, off_time=0.2, n=3, background=True)

# Bind hardware interrupt
reset_button.when_pressed = hardware_reset_action

# ==========================================
# WEB ROUTES
# ==========================================
@app.route('/')
def index():
    """Serves the root status page."""
    return "<h1>Pi 5 Embedded Web Server</h1><p>System Online. Use /api/led to interact.</p>"

@app.route('/api/led', methods=['GET', 'POST'])
def control_led():
    """API endpoint to read or toggle the status LED."""
    if request.method == 'POST':
        try:
            status_led.toggle()
            state = "ON" if status_led.is_lit else "OFF"
            logging.info(f"LED toggled via API. New state: {state}")
            return jsonify({"status": "success", "led_state": state}), 200
        except Exception as e:
            logging.error(f"API LED toggle failed: {e}")
            return jsonify({"error": "Hardware control failed"}), 500
    
    # GET request
    return jsonify({"led_state": "ON" if status_led.is_lit else "OFF"}), 200

# ==========================================
# ENTRY POINT
# ==========================================
if __name__ == '__main__':
    # Note: In production, Gunicorn handles the serving.
    # This block is for local development/testing only.
    try:
        logging.info("Starting development server on port 5000...")
        app.run(host='127.0.0.1', port=5000, debug=False)
    except OSError as e:
        if "Address already in use" in str(e):
            logging.critical("Fatal: Port 5000 is bound by another process. Kill it via `sudo fuser -k 5000/tcp`.")
        else:
            logging.critical(f"Fatal OS Error: {e}")
        sys.exit(1)
    finally:
        # Clean up GPIO on exit
        status_led.close()
        reset_button.close()

Debugging: "502 Bad Gateway" and Common Failure Modes

When your web server fails, the browser output is rarely enough to diagnose the root cause. Here are the exact error strings you will encounter and how to fix them.

The First Three Things to Check When It Fails:

1. Gunicorn Service Status: Run systemctl status gunicorn. If it's "failed", check the journal with journalctl -u gunicorn -n 50.
2. Nginx Error Logs: Run sudo tail -f /var/log/nginx/error.log. This will tell you if Nginx can't reach the upstream Gunicorn socket.
3. Firewall Rules: Run sudo ufw status. If active, ensure port 80 is allowed via sudo ufw allow 'Nginx Full'.

Ranked Causes for Specific Errors

Error 1: 502 Bad Gateway

• Cause A (Most Likely): Gunicorn crashed or isn't running. Nginx is trying to proxy to port 5000, but nothing is listening. Fix: sudo systemctl restart gunicorn.
• Cause B: Port mismatch. Your Nginx config says proxy_pass http://127.0.0.1:8000; but Gunicorn is bound to 5000. Fix: Align the ports in both configs.

Error 2: [Errno 98] Address already in use

• Cause A: You ran the Flask development server manually (python3 app.py) in the background, and now Gunicorn is trying to bind to the same port. Fix: Kill the zombie process with sudo fuser -k 5000/tcp.
• Cause B: Gunicorn didn't release the socket gracefully after a crash. Fix: Restart the service.

Error 3: RuntimeError: No access to /dev/mem. Try running as root!

• Cause A: You are using an outdated GPIO library (like the legacy RPi.GPIO) on Raspberry Pi OS Bookworm. Fix: Switch to gpiozero which uses the lgpio backend, or ensure your user is in the gpio and dialout groups via sudo usermod -aG gpio,dialout $USER.

Extending and Simplifying Your Pi Web Server

How to Simplify:
If you are only building a local dashboard and don't care about concurrent connections or SSL termination, you can drop Nginx entirely. Run Gunicorn directly on 0.0.0.0:80 (requires root/CAP_NET_BIND_SERVICE) or port 8080. This removes a layer of configuration but exposes your Python app directly to the network, which is not recommended for internet-facing deployments.

How to Extend:
To make this server accessible from the internet without opening ports on your home router (which invites botnet scanning), use Cloudflare Tunnels. Install cloudflared on the Pi, authenticate it, and route your local http://localhost:80 to a public domain. This provides free, automatic HTTPS and hides your home IP address.

For hardware extensions, swap the simple LED for an I2C BME280 environmental sensor. Add a cron job that writes temperature and humidity data to a local SQLite database every 60 seconds, and create a new /api/sensors Flask route to serve the JSON data to a frontend charting library like Chart.js.

For authoritative configuration details, always refer to the official Raspberry Pi OS configuration documentation and the Flask deployment guidelines to ensure your production environment remains secure and stable.