How to Host a Website from Raspberry Pi: Zero 2 W Sensor Dashboard

If you want to host a website from Raspberry Pi hardware for an embedded sensor dashboard, the most reliable approach is using a Raspberry Pi Zero 2 W running Raspberry Pi OS Lite (64-bit) with a Python Flask backend served by Gunicorn. This setup draws under 1.5A at peak load, avoids the bloat of a full desktop environment, and provides a robust REST API for frontend frameworks or direct browser polling.

Below is the complete bench-tested build for a live environmental dashboard. We will wire a BME280 sensor via I2C, write the fault-tolerant Python server, and cover the exact debugging steps when the I2C bus or network stack inevitably throws an error.

Hardware Spec Sheet & Bill of Materials

Before flashing an SD card, verify your hardware. The code and pin mappings below specifically target the Raspberry Pi Zero 2 W, though they are 100% compatible with the Pi 4 Model B and Pi 5. The Pi Zero 2 W is preferred here for its low idle power draw (~120mA), making it ideal for 24/7 embedded web hosting on a small UPS or solar battery bank.

GPIO & I2C Pin Mapping

The BME280 communicates over the primary I2C bus. We are also adding a status LED on GPIO 17 to blink when a web request is processed, which is invaluable for debugging headless network issues from across the workbench.

OS Provisioning & Network Configuration

Do not install the desktop version of Raspberry Pi OS. It wastes RAM and CPU cycles on X11/Wayland rendering that a headless web server does not need.

1. Flash the OS: Use Raspberry Pi Imager to flash Raspberry Pi OS Lite (64-bit). In the advanced settings (Ctrl+Shift+X), enable SSH, set your username/password, and configure your WiFi SSID.
2. Enable I2C: SSH into the Pi and run sudo raspi-config. Navigate to Interface Options > I2C and enable it. Reboot.
3. Verify I2C Bus: Install tools and scan the bus: sudo apt install i2c-tools && i2cdetect -y 1. You should see 76 or 77 in the grid. If the grid is empty, check your wiring.
4. Install Python Dependencies: Create a virtual environment to keep system packages clean.
   sudo apt install python3-venv python3-pip
python3 -m venv venv && source venv/bin/activate
pip install Flask smbus2 RPi.bme280 RPi.GPIO gunicorn
5. Set a Static IP: Edit /etc/dhcpcd.conf (or configure via your router's DHCP reservation) to ensure the Pi's IP doesn't change after a power outage, which will break your bookmarks and DNS records.

The Python Web Server Code

This Flask application exposes a single JSON endpoint. It includes explicit pin definitions, hardware cleanup routines, and a try/except block to prevent the web server from crashing if the I2C bus temporarily locks up due to electrical noise.

# app.py
from flask import Flask, jsonify
import smbus2
import bme280
import RPi.GPIO as GPIO
import atexit

app = Flask(__name__)

# --- Pin & Hardware Definitions ---
STATUS_LED_PIN = 17
I2C_BUS = 1
BME280_ADDR = 0x76  # Change to 0x77 if your breakout board has the alternate address

# --- Hardware Initialization ---
GPIO.setmode(GPIO.BCM)
GPIO.setup(STATUS_LED_PIN, GPIO.OUT)
GPIO.output(STATUS_LED_PIN, GPIO.LOW)

bus = smbus2.SMBus(I2C_BUS)
try:
    calibration_params = bme280.load_calibration_params(bus, BME280_ADDR)
except Exception as e:
    print(f'FATAL: Could not initialize BME280 at {hex(BME280_ADDR)}. Check wiring. Error: {e}')
    exit(1)

# Ensure GPIO pins are reset if the app crashes or stops
def cleanup_gpio():
    GPIO.cleanup()

atexit.register(cleanup_gpio)

# --- API Route ---
@app.route('/api/sensors')
def get_sensors():
    GPIO.output(STATUS_LED_PIN, GPIO.HIGH)  # Blink LED on request
    try:
        data = bme280.sample(bus, BME280_ADDR, calibration_params)
        GPIO.output(STATUS_LED_PIN, GPIO.LOW)
        return jsonify({
            'temp_c': round(data.temperature, 2),
            'humidity': round(data.humidity, 2),
            'pressure_hpa': round(data.pressure, 2)
        })
    except Exception as e:
        GPIO.output(STATUS_LED_PIN, GPIO.LOW)
        # Return 500 Internal Server Error with the exact hardware fault
        return jsonify({'error': 'Sensor read failed', 'detail': str(e)}), 500

if __name__ == '__main__':
    # Dev server only. Use Gunicorn for production.
    app.run(host='0.0.0.0', port=5000)

To run this in a production-ready manner, do not use the Flask development server. Use Gunicorn to handle concurrent requests and bind it to port 80:

sudo gunicorn -w 2 -b 0.0.0.0:80 app:app

For persistent hosting, wrap this command in a systemd service file so it restarts automatically on boot. Refer to the official Flask Gunicorn deployment guide for the exact systemd unit file syntax.

Debugging: I2C Faults & Connection Refused Errors

When hosting a website from Raspberry Pi hardware on a workbench, things will break. Here are the exact error strings you will encounter and how to fix them.

Error 1: OSError: [Errno 121] Remote I/O error

Symptom: The Flask app crashes or returns a 500 error when you hit the /api/sensors endpoint. The console throws this exact OSError.

Ranked Causes & Fixes:

1. Loose Dupont Wires (90% of cases): I2C is highly sensitive to contact resistance. Swap your jumper wires or solder the header directly to the BME280 breakout.
2. Wrong I2C Address (8%): Some BME280 boards default to 0x77 instead of 0x76. Run i2cdetect -y 1 and update the BME280_ADDR variable in the Python code.
3. Missing Pull-up Resistors (2%): If using a cheap clone sensor board without onboard pull-ups, the Pi's internal 1.8kΩ resistors aren't strong enough. Add 4.7kΩ external pull-ups to 3.3V.

Error 2: curl: (7) Failed to connect to 192.168.x.x port 80: Connection refused

Symptom: You try to load the website from your laptop browser, but the connection is immediately rejected.

Ranked Causes & Fixes:

1. Gunicorn Bound to localhost: If you ran gunicorn app:app without the -b 0.0.0.0:80 flag, it only listens on 127.0.0.1. Restart with the explicit bind flag.
2. Firewall Blocking Port 80: If you have ufw enabled, run sudo ufw allow 80/tcp.
3. Port 80 Privilege Issue: Binding to ports below 1024 requires root. Ensure you are running the Gunicorn command with sudo, or configure setcap to allow Python to bind to low ports.

Extending vs. Simplifying the Architecture

Once the baseline API is hosting successfully, you need to decide whether to scale the project up for production or scale it down to save power.

How to Extend (Production & External Access)

If you need to access this dashboard from outside your local network, do not use port forwarding on your home router. Exposing a raw Pi to the public internet is a security risk. Instead, use Cloudflare Tunnels.

• Reverse Proxy: Install Nginx (sudo apt install nginx) to sit in front of Gunicorn. Nginx handles SSL termination, static file caching, and rate limiting, while Gunicorn strictly handles Python execution.
• Secure External Routing: Install cloudflared on the Pi. It creates an outbound-only tunnel to Cloudflare's edge network, allowing you to map dashboard.yourdomain.com to your Pi's local port 80 without opening any inbound firewall ports.
• Database Integration: Instead of just returning the live sample, use the sqlite3 Python library to log every reading to a local database, and add a /api/history endpoint.

How to Simplify (Ultra-Low Power)

If you realize that running a full Linux kernel just to serve a single JSON payload is overkill, or if you need to run the node on a 18650 lithium cell for months, drop the Raspberry Pi entirely.

• Switch to MicroPython: Use a Raspberry Pi Pico W ($6). It runs MicroPython, connects via WiFi, and can host a basic HTTP server using the network and socket modules.
• Trade-offs: You lose the robust Linux networking stack, systemd service management, and easy SSH debugging. However, your idle current drops from ~120mA (Pi Zero 2 W) to ~25mA (Pico W with WiFi sleeping), drastically reducing your battery bank sizing requirements for off-site installs.

Hosting a website from Raspberry Pi hardware bridges the gap between bare-metal microcontrollers and enterprise cloud servers. By keeping the OS headless, handling I2C faults gracefully in your Python code, and securing your external access via tunnels, you build a dashboard that survives long after you have packed up your soldering iron.