DEV Community: Natsuki

Why I Run Nginx on My OpenWrt Router (And How You Can Too)

Natsuki — Fri, 16 Jan 2026 07:21:41 +0000

TL;DR

Your router already handles all network traffic. Why not let it handle reverse proxying too? Running nginx on OpenWrt eliminates an extra hop, simplifies your network architecture, and gives you a single point of SSL termination. This post covers why OpenWrt is the right choice, what nginx actually does, and how to configure it using OpenWrt’s UCI system to proxy 25+ homelab services with clean subdomain URLs.

📦 This nginx setup runs on my DeskPi 12U homelab in a 10sqm Tokyo apartment. See the full setup: Small But Mighty Homelab: DeskPi 12U Running 20+ Services.

Contents:

Why OpenWrt?
What is Nginx and Why Do You Need It?
Why Run Nginx on Your Router?
Installing Nginx on OpenWrt
Understanding OpenWrt’s UCI Configuration
Setting Up Wildcard SSL Certificates
Adding Your First Service
DNS Configuration with dnsmasq
Real Example: 25 Services Proxied Through One Router
Tips and Considerations

1. Why OpenWrt?

Before diving into nginx, let’s talk about why OpenWrt is the foundation that makes this setup possible.

OpenWrt is a Linux distribution designed for embedded devices, primarily routers. Unlike the locked-down firmware that comes with consumer routers, OpenWrt gives you a full Linux system with:

Package management : Install what you need, remove what you don’t
SSH access : Full command-line control over your network
Customizable firewall : iptables/nftables with granular control
Real services : Run nginx, wireguard (for remote access to your homelab), adblock, and more natively

Most consumer router firmware is a black box. You get a web UI with limited options and no way to extend functionality. OpenWrt turns your router into a proper Linux server that happens to also route packets.

Hardware Matters

Not all routers can run OpenWrt well. You need:

Sufficient RAM : 256MB minimum, 512MB+ recommended for nginx
Storage : Internal flash or USB storage for configs
CPU : Modern ARM or MIPS processors handle nginx easily

Check the OpenWrt Table of Hardware to see if your router is supported.

I’m running the OpenWrt One - a router specifically designed for OpenWrt with 1GB RAM and 256MB NAND storage. It runs nginx with 25+ reverse proxy configurations without breaking a sweat.

2. What is Nginx and Why Do You Need It?

Nginx (pronounced “engine-x”) is a high-performance web server and reverse proxy. In a homelab context, you’ll primarily use it as a reverse proxy - a server that sits between your clients and your backend services.

The Problem Nginx Solves

Without a reverse proxy, accessing your homelab services looks like this:

Grafana: http://192.168.1.201:3000
Home Assistant: http://192.168.1.213:8123
Jellyfin: http://192.168.1.201:8096

This approach has several issues:

Memorizing IPs and ports is tedious
No HTTPS means credentials sent in plaintext
Port conflicts when services want the same port
No centralized access control

With nginx as a reverse proxy:

Grafana: https://grafana.raspberrypi.home
Home Assistant: https://homeassistant.raspberrypi.home
Jellyfin: https://jellyfin.raspberrypi.home

How Reverse Proxying Works

Client requests https://grafana.raspberrypi.home
DNS resolves to your router’s IP (192.168.1.1)
Nginx receives the request, terminates SSL
Nginx looks at the hostname (SNI), routes to the correct backend
Backend responds, nginx forwards response to client

The key insight: nginx uses the hostname (Server Name Indication) to route traffic. All services share ports 80/443, but nginx routes based on which subdomain you’re requesting.

3. Why Run Nginx on Your Router?

You could run nginx anywhere - a Raspberry Pi, a VM, a Docker container. So why specifically on the router?

Elimination of Extra Hops

Every network request already goes through your router. If nginx runs on a separate machine, you add an extra hop:

One less hop means lower latency, less routing rules, and one less point of failure.

Single Point of Configuration

Your router already manages:

DHCP (IP assignments)
DNS (name resolution via dnsmasq)
Firewall rules

Adding reverse proxying to this list keeps all network configuration in one place. When you add a new service, you configure the DNS entry and nginx proxy in the same system.

Always-On Guarantee

Your router is the one device that’s always running. If it’s down, you have no network anyway. Running nginx on the router means your reverse proxy has the same uptime as your network itself.

Resource Efficiency

Modern routers have more than enough power for reverse proxying. Nginx is extremely lightweight - it was designed to handle thousands of concurrent connections on minimal hardware. My OpenWrt One barely notices the 25 proxy configurations:

 total used free shared buff/cache available
Mem: 1011248 163144 241180 505676 606924 291924

Less than 200MB used with nginx, dnsmasq, and all other services running.

4. Installing Nginx on OpenWrt

SSH into your router and install nginx:

opkg update
opkg install nginx-ssl

The nginx-ssl package includes SSL/TLS support. Without it, you can only proxy HTTP.

Enable and start the service:

/etc/init.d/nginx enable
/etc/init.d/nginx start

Verify it’s running:

nginx -v
# nginx version: nginx/1.26.1 (x86_64-pc-linux-gnu)

5. Understanding OpenWrt’s UCI Configuration

OpenWrt uses UCI (Unified Configuration Interface) to manage all system configuration, including nginx. Instead of editing nginx config files directly, you define settings through UCI and OpenWrt generates the actual nginx config at /var/lib/nginx/uci.conf on each restart.

Nginx configuration on OpenWrt has two parts:

Server blocks (via UCI) - Define which subdomain to listen for and which SSL certificate to use
Location files (plain nginx config) - Define where to proxy the traffic

Part 1: Server Block (UCI)

A server block tells nginx: “When someone requests this subdomain, use this SSL certificate and look at this location file for routing rules.”

uci set nginx.srv_grafana=server
uci set nginx.srv_grafana.uci_enable='true'
uci set nginx.srv_grafana.server_name='grafana.raspberrypi.home'
uci set nginx.srv_grafana.include='conf.d/grafana.locations'
uci set nginx.srv_grafana.ssl_certificate='/etc/nginx/ssl/wildcard.raspberrypi.home.crt'
uci set nginx.srv_grafana.ssl_certificate_key='/etc/nginx/ssl/wildcard.raspberrypi.home.key'
uci add_list nginx.srv_grafana.listen='443 ssl'
uci add_list nginx.srv_grafana.listen='[::]:443 ssl'
uci set nginx.srv_grafana.ssl_session_cache='shared:SSL:32k'
uci set nginx.srv_grafana.ssl_session_timeout='64m'
uci commit nginx
/etc/init.d/nginx restart

The key line is server_name - this enables SNI (Server Name Indication). When a client connects to port 443 and says “I want grafana.raspberrypi.home”, nginx matches it to this server block.

Part 2: Location File

The location file tells nginx where to actually send the traffic. Create /etc/nginx/conf.d/grafana.locations:

location / {
 proxy_pass http://192.168.1.201:3000;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
}

proxy_pass - The backend server address and port
Upgrade / Connection - Enable WebSocket support
X-Real-IP / X-Forwarded-For - Pass the client’s real IP to the backend
X-Forwarded-Proto - Tell the backend the original request was HTTPS

6. Setting Up Wildcard SSL Certificates

Instead of managing certificates for each subdomain, use a wildcard certificate that covers *.raspberrypi.home.

Generating a Self-Signed Wildcard Certificate

On your router or any Linux machine with OpenSSL:

# Generate private key
openssl genrsa -out wildcard.raspberrypi.home.key 2048

# Generate certificate signing request
openssl req -new -key wildcard.raspberrypi.home.key \
 -out wildcard.raspberrypi.home.csr \
 -subj "/CN=*.raspberrypi.home"

# Generate self-signed certificate (valid for 10 years)
openssl x509 -req -days 3650 \
 -in wildcard.raspberrypi.home.csr \
 -signkey wildcard.raspberrypi.home.key \
 -out wildcard.raspberrypi.home.crt

Place the files in /etc/nginx/ssl/:

mkdir -p /etc/nginx/ssl
mv wildcard.raspberrypi.home.* /etc/nginx/ssl/
chmod 600 /etc/nginx/ssl/*.key

Browser Trust

Self-signed certificates will show browser warnings until you install them. Import wildcard.raspberrypi.home.crt into your browser or OS trust store to make the warnings go away. On most systems, double-clicking the certificate file will open an import wizard.

7. Adding Your First Service

Let’s add a complete example for Home Assistant:

Step 1: Create the Location File

Create /etc/nginx/conf.d/homeassistant.locations:

location / {
 proxy_pass http://192.168.1.213:8123;
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;

 # Home Assistant specific settings
 proxy_buffering off;
 proxy_request_buffering off;
 chunked_transfer_encoding on;
 tcp_nodelay on;
 proxy_read_timeout 3600s; # Long timeout for WebSocket connections
}

Home Assistant uses WebSockets heavily, so we disable buffering and set a long read timeout.

Step 2: Add UCI Configuration

uci set nginx.srv_homeassistant=server
uci set nginx.srv_homeassistant.uci_enable='true'
uci set nginx.srv_homeassistant.server_name='homeassistant.raspberrypi.home'
uci set nginx.srv_homeassistant.include='conf.d/homeassistant.locations'
uci set nginx.srv_homeassistant.ssl_certificate='/etc/nginx/ssl/wildcard.raspberrypi.home.crt'
uci set nginx.srv_homeassistant.ssl_certificate_key='/etc/nginx/ssl/wildcard.raspberrypi.home.key'
uci add_list nginx.srv_homeassistant.listen='443 ssl'
uci add_list nginx.srv_homeassistant.listen='[::]:443 ssl'
uci set nginx.srv_homeassistant.ssl_session_cache='shared:SSL:32k'
uci set nginx.srv_homeassistant.ssl_session_timeout='64m'
uci commit nginx
/etc/init.d/nginx restart

Step 3: Verify

Check nginx configuration is valid:

nginx -t

8. DNS Configuration with dnsmasq

For subdomains to resolve to your router, configure dnsmasq (OpenWrt’s built-in DNS server).

Wildcard DNS Entry

The cleanest approach is a wildcard entry that routes all *.raspberrypi.home to your router:

uci set dhcp.@dnsmasq[0].domain='raspberrypi.home'
uci add dhcp domain
uci set dhcp.@domain[-1].name='raspberrypi.home'
uci set dhcp.@domain[-1].ip='192.168.1.1'
uci commit dhcp
/etc/init.d/dnsmasq restart

Now any *.raspberrypi.home request resolves to 192.168.1.1, where nginx handles routing based on the subdomain.

Testing DNS Resolution

From any device on your network:

nslookup grafana.raspberrypi.home
# Should return 192.168.1.1

nslookup anything.raspberrypi.home
# Also returns 192.168.1.1

9. Real Example: 25 Services Proxied Through One Router

Here’s my actual setup - services running across Raspberry Pis, an N305 mini PC, and other devices, all proxied through the OpenWrt One. Every service accessible via clean subdomain URLs with HTTPS:

Service	Subdomain	Backend
Homer (Dashboard)	homer.raspberrypi.home	192.168.1.201:8080
Grafana	grafana.raspberrypi.home	192.168.1.201:3000
Prometheus	prometheus.raspberrypi.home	192.168.1.201:9090
Home Assistant	homeassistant.raspberrypi.home	192.168.1.213:8123
Jellyfin	jellyfin.raspberrypi.home	192.168.1.201:8096
Portainer	portainer.raspberrypi.home	192.168.1.201:9000
Bitwarden	bitwarden.raspberrypi.home	192.168.1.201:8081
qBittorrent	qbittorrent.raspberrypi.home	192.168.1.201:8090
Komga	komga.raspberrypi.home	192.168.1.201:8082
Uptime Kuma	uptimekuma.raspberrypi.home	192.168.1.201:3001
Syncthing	syncthing.raspberrypi.home	192.168.1.201:8384
Guacamole	guacamole.raspberrypi.home	192.168.1.201:8083
PiKVM	pikvm.raspberrypi.home	192.168.1.100:443
OctoPrint	octopi.raspberrypi.home	192.168.1.101:80
…	…	…

Every service is accessed through https://servicename.raspberrypi.home on port 443. You don’t need to remember different port numbers - nginx reads the subdomain from the URL and forwards your request to the correct backend service internally.

10. Tips and Considerations

Logging

OpenWrt centralizes all logs through logread. To view nginx logs:

logread | grep nginx

By default, access logging is disabled (access_log off) since router storage is limited. Error logs still go to the system log and are accessible via logread.

Backup Your Configuration

UCI configurations live in /etc/config/. Location files are in /etc/nginx/conf.d/. Back these up:

# Create backup
tar -czf nginx-backup.tar.gz /etc/config/nginx /etc/nginx/conf.d/ /etc/nginx/ssl/

# Restore
tar -xzf nginx-backup.tar.gz -C /

Service-Specific Configuration

Some services need to know they’re behind a reverse proxy. Nginx alone isn’t enough - you need to configure the service itself. For example, Grafana requires:

environment:
 - GF_SERVER_ROOT_URL=https://grafana.yourdomain.home

Without this, Grafana fails to load its assets through the proxy. Check your service’s documentation for reverse proxy settings if things don’t work after setting up nginx.

What’s Next

This post covered local access to your homelab services. In an upcoming post, I’ll cover remote access - setting up WireGuard on OpenWrt to securely reach your services from anywhere.

Conclusion

Running nginx on your OpenWrt router leverages hardware you already have running 24/7. It eliminates network hops, centralizes configuration with DNS, and provides a clean subdomain-based access pattern for all your services.

The combination of OpenWrt’s UCI system and nginx’s flexibility creates a maintainable setup that scales from a handful of services to dozens. My 25-service configuration runs on minimal resources and has been rock solid.

Start with one or two services, get comfortable with the UCI workflow, and expand from there. Your router is more capable than you might think.

I write weekly about homelabs, monitoring, and DevOps. If you found this helpful, check out my other posts or subscribe on Dev.to for more practical guides like this one.

End-to-End Monitoring Explained for Homelabs: Prometheus, Grafana & Alertmanager

Natsuki — Fri, 09 Jan 2026 20:34:29 +0000

TL;DR

When you’re running a homelab with dozens of containers and services, things will eventually break. The question isn’t if something will fail, but when - and whether you’ll know about it before your users do.

This post walks through building a production-grade monitoring stack using Prometheus + Grafana that monitors 37 containers across 2 hosts, with automatic email alerting and comprehensive dashboards. You’ll get visibility into CPU, memory, disk, network, container metrics, and even ZFS storage - all with 30 days of historical data.

Full Configuration is available on GitHub. Clone and customize for your homelab.

📦 This monitoring stack runs on my DeskPi 12U homelab in a 10sqm Tokyo apartment. See the full setup: Small But Mighty Homelab: DeskPi 12U Running 20+ Services.

Contents:

Why Monitor Your Homelab?
The Stack Overview
Architecture
Docker Compose Setup
Prometheus Configuration
Node Exporter for Host Metrics
cAdvisor for Container Metrics
Grafana Setup & Data Source
Building Dashboards
Alert Rules
Alertmanager & Notifications
Tips & Lessons Learned
What’s Next?

1. Why Monitor Your Homelab?

A proper monitoring stack gives you three critical capabilities:

Visibility : Know what’s happening right now across all your services
Alerting : Get notified when things go wrong, before they become critical
Debugging : Historical data to troubleshoot issues and understand trends

2. The Stack Overview

I chose the classic observability stack that’s proven itself in production environments:

Node Exporter : Exposes system-level metrics (CPU, memory, disk, network)
cAdvisor : Collects container resource usage and performance metrics
Prometheus : Time-series database that scrapes and stores metrics
Grafana : Visualization platform for creating dashboards
Alertmanager : Handles alert routing and notifications

Why this stack? It’s open-source, widely adopted, handles homelab scale easily, and doesn’t require expensive licensing.

3. Architecture

My homelab runs on Proxmox - a bare-metal hypervisor that lets me run multiple isolated workloads on the same hardware without the overhead of full VMs. I use LXC containers as lightweight virtual environments, and run Docker inside the LXC containers.

The monitoring stack (Prometheus, Grafana, Alertmanager, cAdvisor) runs in Docker containers inside an LXC. Node Exporter runs natively on each Proxmox host (outside the LXC) because running it inside Docker-in-LXC reports incorrect memory metrics due to nested containerization.

My setup monitors two hosts:

Raspberry Pi 5 (192.168.1.201): Running the monitoring stack itself
N305 Server (192.168.1.50): Main server running 29 containers (Immich, Bitwarden, Jellyfin, etc.)

4. Docker Compose Setup

The monitoring stack runs entirely in Docker on the Raspberry Pi 5. Here’s the complete docker-compose.yml:

networks:
 internal:
 driver: bridge

services:
 prometheus:
 container_name: monitoring-prometheus
 image: prom/prometheus:latest
 hostname: rpi-prometheus
 restart: unless-stopped
 user: "nobody"
 networks:
 - internal
 ports:
 - "9090:9090"
 command:
 - '--config.file=/etc/prometheus/prometheus.yml'
 - '--storage.tsdb.path=/prometheus'
 - '--storage.tsdb.retention.time=30d'
 - '--web.enable-admin-api'
 volumes:
 - /home/ubuntu/docker/prometheus/config:/etc/prometheus
 - /home/ubuntu/docker/prometheus/data:/prometheus
 depends_on:
 - cadvisor
 - alertmanager
 links:
 - cadvisor:cadvisor
 - alertmanager:alertmanager

 grafana:
 container_name: monitoring-grafana
 image: grafana/grafana:latest
 hostname: rpi-grafana
 restart: unless-stopped
 user: "472"
 networks:
 - internal
 ports:
 - "3000:3000"
 volumes:
 - /home/ubuntu/docker/grafana/data:/var/lib/grafana
 - /home/ubuntu/docker/grafana/provisioning:/etc/grafana/provisioning
 depends_on:
 - prometheus

 alertmanager:
 container_name: monitoring-alertmanager
 image: prom/alertmanager:latest
 hostname: rpi-alertmanager
 restart: unless-stopped
 networks:
 - internal
 ports:
 - "9093:9093"
 volumes:
 - /home/ubuntu/docker/alertmanager:/etc/alertmanager
 command:
 - '--config.file=/etc/alertmanager/alertmanager.yml'
 - '--storage.path=/alertmanager'

 cadvisor:
 container_name: monitoring-cadvisor
 image: gcr.io/cadvisor/cadvisor:v0.49.1
 hostname: rpi-cadvisor
 restart: unless-stopped
 privileged: true
 networks:
 - internal
 expose:
 - 8080
 command:
 - '-housekeeping_interval=15s'
 - '-docker_only=true'
 - '-store_container_labels=false'
 devices:
 - /dev/kmsg
 volumes:
 - /:/rootfs:ro
 - /var/run:/var/run:rw
 - /sys:/sys:ro
 - /var/lib/docker/:/var/lib/docker:ro
 - /dev/disk/:/dev/disk:ro
 - /etc/machine-id:/etc/machine-id:ro

Key configuration details:

30-day retention : Prometheus keeps 30 days of metrics data
15-second housekeeping : cAdvisor updates container metrics every 15 seconds
Privileged cAdvisor : Required to read container metrics from the host
Internal network : Services communicate via Docker network, only exposing necessary ports

5. Prometheus Configuration

Prometheus is a time-series database that stores metrics as data points with timestamps. It works by periodically “scraping” (pulling) metrics from configured endpoints over HTTP. Each scrape collects current metric values and stores them with a timestamp, allowing you to query historical trends.

The key concept: Prometheus pulls metrics - it doesn’t wait for services to push data. This means your services need to expose a /metrics endpoint that Prometheus can scrape.

Prometheus needs to know what to scrape. Here’s my prometheus.yml:

global:
 scrape_interval: 15s
 evaluation_interval: 15s

alerting:
 alertmanagers:
 - static_configs:
 - targets:
 - alertmanager:9093

rule_files:
 - "alerts/*.yml"

scrape_configs:
 # Prometheus itself
 - job_name: 'prometheus'
 scrape_interval: 5s
 static_configs:
 - targets: ['localhost:9090']

 # Raspberry Pi 5 - Node Exporter
 - job_name: 'monitoring-host-node'
 scrape_interval: 15s
 static_configs:
 - targets: ['192.168.1.201:9100']
 labels:
 host: 'monitoring-host'
 instance_name: 'rpi-monitoring'

 # Raspberry Pi 5 - cAdvisor
 - job_name: 'monitoring-host-cadvisor'
 scrape_interval: 15s
 static_configs:
 - targets: ['cadvisor:8080']
 labels:
 host: 'monitoring-host'
 instance_name: 'rpi-monitoring'

 # N305 - Node Exporter
 - job_name: 'n305-node'
 scrape_interval: 15s
 static_configs:
 - targets: ['192.168.1.50:9100']
 labels:
 host: 'n305'
 instance_name: 'n305-server'

 # N305 - cAdvisor
 - job_name: 'n305-cadvisor'
 scrape_interval: 15s
 static_configs:
 - targets: ['192.168.1.50:8080']
 labels:
 host: 'n305'
 instance_name: 'n305-server'

Important notes :

Jobs : A “job” groups related scrape targets together (e.g., monitoring-host-node, n305-cadvisor). Prometheus automatically adds a job label to every metric, so you can filter by job in queries. I use separate jobs for Node Exporter vs cAdvisor metrics.
Custom labels : Each target gets host and instance_name labels for easier filtering
15-second scrapes : Balance between data granularity and resource usage
Alert rules : Loaded from separate files in alerts/ directory

6. Node Exporter for Host Metrics

Node Exporter is a Prometheus exporter that exposes hardware and OS-level metrics from Linux systems. It runs as a service on each host and provides a /metrics HTTP endpoint that Prometheus can scrape.

Think of it as a bridge between your system’s kernel statistics (CPU, memory, disk, network) and Prometheus. It reads data from /proc, /sys, and other system sources, then formats it into Prometheus-compatible metrics.

Node Exporter runs natively (not in Docker) on both hosts to collect system-level metrics.

Installation

# Install Node Exporter
wget https://github.com/prometheus/node_exporter/releases/download/v1.7.0/node_exporter-1.7.0.linux-amd64.tar.gz
tar xvfz node_exporter-1.7.0.linux-amd64.tar.gz
sudo cp node_exporter-1.7.0.linux-amd64/node_exporter /usr/local/bin/

Systemd Service

Create /etc/systemd/system/node_exporter.service:

[Unit]
Description=Node Exporter
After=network.target

[Service]
Type=simple
User=node_exporter
ExecStart=/usr/local/bin/node_exporter

[Install]
WantedBy=multi-user.target


sudo useradd -rs /bin/false node_exporter
sudo systemctl daemon-reload
sudo systemctl enable node_exporter
sudo systemctl start node_exporter

Why native instead of Docker? I initially ran Node Exporter in Docker within LXC containers, but it reported incorrect memory usage (0.1% instead of actual 40%). Running it natively on the host gives accurate metrics.

Node Exporter exposes hundreds of metrics at :9100/metrics, including:

CPU usage per core and mode (user, system, idle, iowait)
Memory (total, available, cached, buffers, swap)
Disk usage and I/O statistics
Network interface traffic and errors
Load averages
Filesystem usage (including ZFS pools!)

The “All Nodes” dashboard displaying N305 system metrics

7. cAdvisor for Container Metrics

cAdvisor (Container Advisor) is Google’s open-source container monitoring tool. It automatically discovers all containers on a host and collects resource usage metrics: CPU, memory, network, and disk I/O per container.

Unlike Node Exporter which monitors the host system, cAdvisor specifically monitors containerized applications. It understands Docker’s resource limits (enforced via Linux cgroups - the kernel feature that isolates container resources) and can show both usage and limits for each container.

cAdvisor runs in Docker and monitors all other containers on the same host.

The key configuration flags:

command:
 - '-housekeeping_interval=15s' # Update metrics every 15s
 - '-docker_only=true' # Only monitor Docker containers
 - '-store_container_labels=false' # Don't store all labels (reduces cardinality)

Why privileged mode? cAdvisor needs access to the host’s cgroups (Linux kernel’s resource isolation mechanism) to read container resource usage:

privileged: true
devices:
 - /dev/kmsg
volumes:
 - /:/rootfs:ro
 - /var/run:/var/run:rw
 - /sys:/sys:ro
 - /var/lib/docker/:/var/lib/docker:ro

cAdvisor provides metrics like:

Container CPU usage (total and per-core)
Container memory usage and limits
Network I/O per container
Disk I/O per container
Container restart counts

cAdvisor dashboard displaying container metrics across all monitored hosts

8. Grafana Setup & Data Source

Grafana is the visualization tool that turns Prometheus metrics into beautiful dashboards and graphs. While Prometheus stores the raw time-series data, Grafana connects to it as a “data source” and uses PromQL (Prometheus Query Language) to query and visualize metrics. You could query Prometheus directly, but Grafana makes it visual and user-friendly.

Initial Setup

After starting Grafana, log in at http://192.168.1.201:3000 (default credentials: admin/admin).

Provisioning Prometheus Data Source

Instead of manually adding the data source, provision it automatically with a YAML file in /home/ubuntu/docker/grafana/provisioning/datasources/prometheus.yml:

apiVersion: 1

datasources:
 - name: Prometheus
 type: prometheus
 access: proxy
 url: http://prometheus:9090
 isDefault: true
 editable: false
 uid: PBFA97CFB590B2093

Important : The uid must match what you use in dashboard JSON files. I learned this the hard way when my dashboards showed “N/A” everywhere because they had a hardcoded UID that didn’t match my actual Prometheus datasource!

9. Building Dashboards

Dashboards transform raw Prometheus metrics into visual panels you can actually understand at a glance. Instead of querying Prometheus manually with PromQL, you build panels (gauges, graphs, stats) that auto-update and show trends over time.

The “All Nodes” dashboard displaying N305 system metrics

The dashboard has 12 panels showing current status and historical trends:

Top row : Colored gauges (CPU 31%, Memory 40.4%, Root FS 58.5%) and stat panels (Load 0.27, Uptime 1.49 days, 8 CPU cores)
Middle section : Network traffic graphs for all interfaces, plus CPU and memory usage time-series
Bottom row : ZFS storage showing 160 GiB used out of 2.3 TB (2.4% full)

You can build this manually by clicking “Add Panel” in Grafana, or export/import dashboard JSON files for faster setup.

Dashboard Variables

Variables make your dashboard reusable across multiple hosts. Instead of hardcoding instance="192.168.1.201:9100" in every query, you use instance="$instance" and select which host to view from a dropdown.

Create these variables in Dashboard settings > Variables:

Job selector (which monitoring job to view):

Name: job
Type: Query
Query: label_values(node_uname_info, job)

Instance selector (which specific host):

Name: instance
Type: Query
Query: label_values(node_uname_info{job="$job"}, instance)

Now you can switch between Raspberry Pi 5 and N305 using dropdowns at the top of the dashboard.

Key PromQL Queries

Here are the queries powering each panel type. PromQL is Prometheus’s query language - it looks intimidating at first, but once you understand a few patterns, it’s straightforward.

Gauge Panels (current value with color thresholds):

# CPU Usage (%)
100 - (avg(rate(node_cpu_seconds_total{mode="idle",instance="$instance",job="$job"}[5m])) * 100)

This calculates CPU usage by measuring how much time the CPU is not idle over a 5-minute window. The rate() function converts cumulative counters into per-second rates.

# Memory Usage (%)
100 * (1 - ((node_memory_MemAvailable_bytes{instance="$instance",job="$job"}) / node_memory_MemTotal_bytes{instance="$instance",job="$job"}))

Uses MemAvailable instead of MemFree because Linux caches unused memory. MemAvailable accounts for reclaimable cache, giving you the real available memory.

# Root Disk Usage (%)
100 - ((node_filesystem_avail_bytes{instance="$instance",job="$job",mountpoint="/"} / node_filesystem_size_bytes{instance="$instance",job="$job",mountpoint="/"}) * 100)

# ZFS Storage (%)
(1 - (node_filesystem_avail_bytes{instance="$instance",job="$job",fstype="zfs",mountpoint="/storage/media"} / node_filesystem_size_bytes{instance="$instance",job="$job",fstype="zfs",mountpoint="/storage/media"})) * 100

Stat Panels (single number display):

# Load Average (1 minute)
node_load1{instance="$instance",job="$job"}

# System Uptime (seconds)
node_time_seconds{instance="$instance",job="$job"} - node_boot_time_seconds{instance="$instance",job="$job"}

# CPU Core Count
count(count(node_cpu_seconds_total{instance="$instance",job="$job"}) by (cpu))

Time-Series Graphs (trends over time):

# CPU Usage History
100 - (avg(rate(node_cpu_seconds_total{mode="idle",instance="$instance",job="$job"}[5m])) * 100)

# Memory Usage History
100 * (1 - ((node_memory_MemAvailable_bytes{instance="$instance",job="$job"}) / node_memory_MemTotal_bytes{instance="$instance",job="$job"}))

# Network Receive Rate (per device)
rate(node_network_receive_bytes_total{instance="$instance",job="$job",device!="lo"}[5m])

# Network Transmit Rate (per device)
rate(node_network_transmit_bytes_total{instance="$instance",job="$job",device!="lo"}[5m])

The device!="lo" filter excludes the loopback interface since you only care about physical network traffic.

10. Alert Rules

Prometheus continuously evaluates alert rules defined in YAML files. When a condition is met for the specified duration (for: 5m), Prometheus fires the alert and sends it to Alertmanager for routing and notification.

Alert rules are defined in separate YAML files loaded by Prometheus.

System Alerts

/home/ubuntu/docker/prometheus/config/alerts/system-alerts.yml:

groups:
 - name: system-alerts
 rules:
 # Disk space critical (<10% free)
 - alert: DiskSpaceLow
 expr: (node_filesystem_avail_bytes{fstype=~"ext4|xfs"} / node_filesystem_size_bytes{fstype=~"ext4|xfs"}) * 100 < 10
 for: 5m
 labels:
 severity: critical
 annotations:
 summary: "Disk space low on {{ $labels.instance }}"
 description: "Disk {{ $labels.mountpoint }} on {{ $labels.instance }} has less than 10% free space ({{ $value | printf \"%.1f\" }}% free)"

 # High memory usage (>90%)
 - alert: HighMemoryUsage
 expr: (1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100 > 90
 for: 5m
 labels:
 severity: warning
 annotations:
 summary: "High memory usage on {{ $labels.instance }}"
 description: "Memory usage on {{ $labels.instance }} is above 90% (current: {{ $value | printf \"%.1f\" }}%)"

 # High CPU usage (>90% for 10 minutes)
 - alert: HighCPUUsage
 expr: 100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 90
 for: 10m
 labels:
 severity: warning
 annotations:
 summary: "High CPU usage on {{ $labels.instance }}"
 description: "CPU usage on {{ $labels.instance }} is above 90% for 10 minutes (current: {{ $value | printf \"%.1f\" }}%)"

 # Host down
 - alert: HostDown
 expr: up{job=~".*node.*"} == 0
 for: 2m
 labels:
 severity: critical
 annotations:
 summary: "Host {{ $labels.instance }} is down"
 description: "Node exporter on {{ $labels.instance }} has been unreachable for more than 2 minutes"

Container Alerts

/home/ubuntu/docker/prometheus/config/alerts/container-alerts.yml:

groups:
 - name: container-alerts
 rules:
 # Container down
 - alert: ContainerDown
 expr: absent(container_last_seen{name=~".+"}) == 1
 for: 2m
 labels:
 severity: critical
 annotations:
 summary: "Container {{ $labels.name }} is down"
 description: "Container {{ $labels.name }} on {{ $labels.host }} has been down for more than 2 minutes"

 # Container high memory (>8GB)
 - alert: ContainerHighMemory
 expr: container_memory_usage_bytes{name=~".+"} > 8589934592
 for: 5m
 labels:
 severity: warning
 annotations:
 summary: "Container {{ $labels.name }} high memory"
 description: "Container {{ $labels.name }} on {{ $labels.host }} memory usage is above 8GB (current: {{ $value | humanize1024 }})"

 # Critical service down (Bitwarden, Immich)
 - alert: CriticalServiceDown
 expr: absent(container_last_seen{name=~"bitwarden|immich-server"})
 for: 1m
 labels:
 severity: critical
 annotations:
 summary: "Critical service {{ $labels.name }} is down"
 description: "Critical service {{ $labels.name }} has been down for more than 1 minute - immediate attention required"

11. Alertmanager & Notifications

Alertmanager receives alerts from Prometheus and handles routing, grouping, deduplication, and notification delivery. It allows complex routing logic - for example, sending critical alerts via SMS and warnings via email, without cluttering your Prometheus alert definitions.

Setting Up Gmail Notifications

Email notification showing alert details with severity level, affected instance, and resolution instructions

Before configuring Alertmanager, you need a Gmail App Password. This takes less than 2 minutes:

Go to https://myaccount.google.com/apppasswords
Sign in to your Google account
Enter “Alertmanager” as the app name
Click “Create”
Copy the 16-character password (you’ll need it for the config below)

Alertmanager Configuration

Configuration file: /home/ubuntu/docker/alertmanager/alertmanager.yml

global:
 resolve_timeout: 5m
 smtp_smarthost: smtp.gmail.com:587
 smtp_from: your-email@gmail.com
 smtp_auth_username: your-email@gmail.com
 smtp_auth_password: "your-app-password" # Use App Password from step 5, not your regular Gmail password. More secure and works with 2FA.
 smtp_require_tls: true

route:
 group_by: [alertname, severity]
 group_wait: 30s
 group_interval: 5m
 repeat_interval: 4h
 receiver: email
 routes:
 - match:
 severity: critical
 receiver: email-critical
 repeat_interval: 1h

receivers:
 - name: email
 email_configs:
 - to: your-email@gmail.com
 send_resolved: true
 headers:
 subject: "[{{ .Status | toUpper }}] {{ .GroupLabels.alertname }}"

 - name: email-critical
 email_configs:
 - to: your-email@gmail.com
 send_resolved: true
 headers:
 subject: "[CRITICAL] {{ .GroupLabels.alertname }}"

# Prevent warning alerts when critical alerts are firing
inhibit_rules:
 - source_match:
 severity: critical
 target_match:
 severity: warning
 equal: [alertname, instance]

Key features :

Multiple notification channels : Supports email (Gmail, Outlook), Slack, Discord, PagerDuty, webhooks, and more. This guide uses Gmail SMTP.
Severity-based routing : Critical alerts repeat every hour, warnings every 4 hours
Alert grouping : Multiple alerts are grouped by name and severity to reduce noise
Inhibition : Critical alerts suppress related warning alerts

12. Tips & Lessons Learned

1. Run Node Exporter Natively in LXC

If you’re running Prometheus in an LXC container, run Node Exporter natively on the host, not in Docker. Docker-in-LXC can report incorrect memory metrics because of the layered containerization.

2. Use Provisioned Datasources

Don’t manually configure Grafana datasources - provision them with YAML files. This makes your setup reproducible and ensures the datasource UID is consistent.

3. Dashboard UID Mismatches Will Haunt You

When importing dashboards, make sure the datasource.uid in panel queries matches your actual Prometheus datasource UID. I spent way too long troubleshooting “N/A” values before realizing my dashboard had a hardcoded UID that didn’t exist.

4. Start Conservative with Alerts

It’s tempting to set aggressive thresholds, but you’ll end up with alert fatigue. Start conservative (90% disk usage, 10-minute CPU sustained) and tighten based on actual incidents.

5. Label Your Scrape Targets

Add custom labels like host and instance_name to your scrape configs. This makes filtering and debugging much easier in Grafana and alert rules.

13. What’s Next?

This monitoring setup covers infrastructure and container metrics, but there’s room for improvement:

Blackbox Exporter : Monitor external endpoints (Is Bitwarden responding? Is Immich up?)
Postgres Exporter : Database metrics for Immich, Plausible, n8n
Loki + Promtail : Centralized log aggregation for debugging
ZFS Health Monitoring : Alert on scrub errors and pool degradation
SSL Certificate Expiry : Get warned before Let’s Encrypt certs expire
SLI/SLO Tracking : Service Level Indicators (response time, uptime %) and Objectives (target 99.9% uptime over certain period) for production-grade reliability engineering
Custom Exporters : Build exporters for applications that don’t expose metrics

Conclusion

This monitoring stack gives you complete visibility into your homelab - 37 containers across 2 hosts, all monitored from a single dashboard with automatic email alerts. The setup works whether you’re running on Proxmox, bare metal, or cloud VMs.

The investment is worth it: you’ll catch issues before they escalate, learn production-grade observability skills, and sleep better knowing your homelab is monitored. The initial 4-hour setup pays for itself the first time it alerts you to a disk filling up or a service crashing.

write weekly about homelabs, monitoring, and DevOps. If you found this helpful, check out my other posts or subscribe on Dev.to for more practical guides like this one.

Small But Mighty Homelab: DeskPi 12U Running 20+ Services

Natsuki — Fri, 02 Jan 2026 11:58:54 +0000

TL;DR

You don't need a server room to run a powerful homelab. With just a few host machines - a couple of Raspberry Pis, a mini PC, and a Jetson - you can run 20+ services: media streaming, photo backup, password management, smart home automation, monitoring, and even a local AI voice assistant. All in a compact, elegant setup that fits in a corner of a tiny apartment.

This post walks through my homelab architecture - how I got here, how it's organized, and what it can do.

Contents:

Evolution
Architecture Overview
Physical Foundation
Network Infrastructure
Compute Hosts & Devices
Services & Applications
Cost Breakdown
Lessons Learned

1. Evolution

Living in a 10 sqm studio apartment in Tokyo, space is extremely limited. Every square centimeter counts.

My homelab started simple: a metal rack with a Raspberry Pi 4 and a hard disk running Samba NAS. As my needs grew, so did the setup.

I moved to a TV rack as services expanded - Home Assistant, monitoring, Docker services. It worked, but:

Cluttered mess of cables
Ate up precious floor space
Collected dust like crazy

The solution? Graduating to a DeskPi 12U rack - vertical consolidation for small spaces, cleaner look, and better dust management.

2. Architecture Overview

3. Physical Foundation

The DeskPi 12U Rack Layout

The DeskPi 12U rack is the physical foundation. It's visually pleasant and prevents dust buildup - a huge improvement over the open TV rack.

Power Management and Cooling

Power comes from a 650W TUF Gaming power supply - repurposed from my old main PC. Plenty of headroom for the entire rack.

For cooling, I installed 2x 12cm fans at the bottom of the rack, providing airflow from bottom to top. This keeps everything running cool without being too noisy.

4. Network Infrastructure

OpenWrt ONE Router

The network starts with an OpenWrt ONE router - an open-source, hacker-friendly device that handles:

Routing, firewall, and DHCP
Nginx reverse proxy for local service names (e.g., jellyfin.local instead of 192.168.1.50:8096)
WireGuard VPN for secure remote access via port forwarding

KP-9000-9XHP-X-AC Managed Switch

The PoE managed switch serves dual purpose:

Network switching for all devices in the rack
PoE power delivery to both Raspberry Pis - eliminating two power adapters and reducing cable clutter

5. Compute Hosts & Devices

Raspberry Pi 4 (PoE-powered)

Role: Smart home automation
Powered via PoE HAT - one less cable to manage

Raspberry Pi 5 (PoE-powered)

Role: Monitoring and observability
Powered via PoE HAT

Intel N305 Mini PC

Role: Main Docker host (Proxmox + LXC container)
Intel i3-N305 (12th gen)
4x Intel i226-V 2.5G NICs
2x NVMe slots, 6x SATA 3.0 bays
DDR5 RAM (32GB), PCIe x1, Type-C
1TB NVMe + 2x 8TB Seagate IronWolf (ZFS mirror)

Why the N305 over other options?

I considered Synology/QNAP NAS devices, used enterprise mini PCs, and Intel NUCs. The N305 NAS board won because:

6 SATA bays - room to expand storage without external enclosures
4x 2.5G NICs - network flexibility for VLANs or link aggregation
Intel Quick Sync - hardware transcoding for Jellyfin without GPU
x86 architecture - better Docker compatibility than ARM alternatives
Low power - efficient enough to run 24/7
DDR5 + NVMe - modern and fast for running 20+ containers

Jetson Nano Orin Super

Role: Local voice assistant

Smart Home Controllers

Philips Hue bridge - Zigbee lighting
SwitchBot hub - SwitchBot devices integration

6. Services & Applications

Smart Home (Pi 4)

Home Assistant - controlling Hue lights, SwitchBot devices, and automations

Monitoring Stack (Pi 5)

Grafana - dashboards and visualization
Prometheus - metrics collection
Alertmanager - alert routing and notifications
Uptime Kuma - service uptime monitoring

Media Stack (N305)

Jellyfin - media streaming with Intel Quick Sync hardware transcoding
Komga - comics/manga reader
Radarr, Sonarr, Prowlarr - media automation (behind Gluetun VPN)
qBittorrent - downloads (behind VPN)
Mylar + Kapowarr - comics management

File Management (N305)

Samba NAS - network file sharing
Filebrowser - web UI for downloads
JDownloader2 - direct downloads
Syncthing - cross-device file sync

Applications (N305)

Vaultwarden - password manager (Bitwarden-compatible)
Immich - photo backup with ML-powered search
Homer - dashboard
n8n - workflow automation
LanguageTool - grammar checker

Voice Assistant (Jetson)

Local voice control via Home Assistant - no cloud required (see my previous post)

Network Services (OpenWrt ONE)

Nginx Reverse Proxy - local service names for easy access, no more remembering IP:port combinations
WireGuard VPN - secure remote access to the homelab when away from home

7. Cost Breakdown

Here's roughly what this setup costs:

Component	Approx. Price
DeskPi RackMate T2 12U	~$100-150
Raspberry Pi 4 4GB	~$60
Raspberry Pi 5 8GB	~$95
PoE+ HAT x2	~$50
Intel N305 NAS motherboard (bare board)	~$200-300
DDR5 RAM (16-32GB)	~$120-400
NVMe SSD (1TB)	~$70-150
NAS HDD (8TB)	~$150-200 each
Jetson Orin Nano Super	~$249
OpenWrt ONE router	~$89
KeepLink PoE managed switch	~$100-150
Misc (cables, fans, accessories)	~$50-100
Total (excl. RAM/storage)	~$1,000-1,250

RAM and storage costs depend on your capacity needs. Due to AI infrastructure demand, DDR5 prices are elevated.

Prices as of January 2026 - check current listings as memory prices are volatile.

Not cheap, but this replaces multiple cloud subscriptions and gives you full control over your data. The N305 and Jetson are the priciest components - you could start smaller with just the Pis and add more later.

8. Lessons Learned

Building this setup taught me a few things:

Go vertical with an enclosed rack - Saves floor space and keeps dust out. The DeskPi 12U rack was a game-changer compared to the open TV rack.
Use PoE where possible - Fewer power adapters, fewer cables, cleaner setup. The managed switch powers both Pis.
Repurpose what you have - The 650W TUF Gaming PSU from my old PC now powers the N305 PC.
Hardware transcoding matters - The N305's Intel Quick Sync handles Jellyfin effortlessly. Choose your hardware with your workloads in mind.
Take your time - Perfecting the setup took a few days. The DeskPi's flexibility with parts and accessories makes it worth the effort.

The rack assembly isn't more complex than building a PC - just more of them. If you can do one, you can do this.

What's Next

This post covered the architecture - the what and why. In upcoming posts, I'll dive into the how: step-by-step guides for setting up each service, from Jellyfin and the *arr stack to Immich and Vaultwarden.

write weekly about homelabs, monitoring, and DevOps. If you found this helpful, check out my other posts or subscribe on Dev.to for more practical guides like this one.

Automated Budget Local LLM Home Assistant Voice Assistant (No Cloud)

Natsuki — Tue, 09 Sep 2025 03:00:00 +0000

Motivation

If you want Google Assistant voice control in Home Assistant, you usually need a Nabu Casa subscription. But I wanted two things:

Save money — no monthly subscription.
Keep my privacy — no smart-home data leaving my LAN.
Utilize my unused gaming PC — put my Intel Arc A580 GPU to work.

So I built my own fully local voice assistant — offline, GPU-accelerated, and integrated with Home Assistant.

Inspiration

This idea was inspired by NetworkChuck's video. He showed how to run a Pi satellite with systemd. I extended the idea into a automated setup powered by Docker Desktop and Task Scheduler.

My Core Idea

I wanted everything to start automatically, run fast on my Intel Arc GPU, and stay simple. My setup is built on five pillars:

Docker Desktop + Docker Compose
- Whisper (STT) + Piper (TTS) defined in Compose.
- Docker Desktop auto-starts on login → containers always online.
Task Scheduler (Windows 11)
- Launches Ollama Portable Zip at login.
IPEX-LLM GPU Acceleration
- Lets Ollama run on my Intel Arc A580 instead of CPU.
Qwen 3-4B Instruct
- Small but capable LLM for intent recognition.
Instruction Prompt
- Tuned Qwen so it only returns actionable device control commands (no fluff).

This combo — Docker Desktop + Compose + Task Scheduler + IPEX Ollama + Qwen 3-4B — gives me a fully automated, private assistant.

Hardware Setup

Raspberry Pi Zero 2 W with ReSpeaker 2-Mic HAT v2
2.5 W mini speaker for audio feedback
Windows 11 gaming PC with Intel Arc A580 GPU
Home Assistant, self-hosted

The Pi works as a Wyoming Satellite. The Windows 11 PC runs Whisper, Piper, and the LLM backend.

Whisper + Piper (Docker Compose on WSL2)

docker-compose.yml

services:
  wyoming-whisper:
    image: rhasspy/wyoming-whisper
    container_name: wyoming-whisper
    ports:
      - "10300:10300"
    volumes:
      - ~/whisperdata:/data
    command: ["--model", "small-int8", "--language", "en"]
    restart: unless-stopped

  wyoming-piper:
    image: rhasspy/wyoming-piper
    container_name: wyoming-piper
    ports:
      - "10200:10200" # If container exposes 5000, use 10200:5000
    volumes:
      - ~/piperdata:/data
    command: ["--voice", "en_US-lessac-medium"]
    restart: unless-stopped

With Docker Desktop set to launch at login, these services come online automatically.

Firewall Rules (PowerShell)

New-NetFirewallRule -DisplayName "Wyoming Piper 10200"   -Direction Inbound -Protocol TCP -LocalPort 10200 -Action Allow
New-NetFirewallRule -DisplayName "Wyoming Whisper 10300" -Direction Inbound -Protocol TCP -LocalPort 10300 -Action Allow
New-NetFirewallRule -DisplayName "Ollama 11436"          -Direction Inbound -Protocol TCP -LocalPort 11436 -Action Allow

Ollama Portable Zip with IPEX-LLM (Intel Arc GPUs)

On my Intel Arc A580, I needed GPU acceleration. Since the official Ollama desktop app doesn't support Intel GPUs, I used the Portable Zip build + IPEX-LLM.

Batch script (run-ollama-gpu.bat)

@echo off
setlocal
set OLLAMA_ROOT=C:\Ollama-IPEX
set OLLAMA_HOST=0.0.0.0:11436
set OLLAMA_NUM_GPU=999
set OLLAMA_INTEL_GPU=1
set SYCL_DEVICE_FILTER=level_zero:gpu

cd /d "%OLLAMA_ROOT%"
timeout /t 10 /nobreak >nul
start "" /min cmd.exe /c "ollama.exe serve >> "%OLLAMA_ROOT%\ollama.log" 2>&1"
endlocal

Task Scheduler

Trigger: At logon (with ~30s delay).
Action: runs run-ollama-gpu.bat.
General tab: Run with highest privileges.

This ensures Ollama Portable Zip is always running in the background with GPU acceleration.

💡 Note for NVIDIA & Apple Users

If you're on NVIDIA GPU or Apple Silicon, you don't need this setup. Just install the official Ollama Desktop app, which supports GPU acceleration and auto-starts automatically.

Integrating with Home Assistant

To connect all endpoints into Home Assistant, there are two steps:

1. Register Wyoming Protocol Services

Go to Settings → Devices & Services → Add Integration → Wyoming Protocol. Add each endpoint as a service:

Whisper (STT): tcp://<PC_IP>:10300
Piper (TTS): tcp://<PC_IP>:10200
(Optional) Pi Satellite: tcp://<pi-ip>:10700

(Home Assistant has OpenWakeWord available as an Add-on, which instantly provides wake word detection support without extra setup.)

2. Create a Voice Assistant

Go to Settings → Voice Assistants and create a new assistant:

Wake Word: Select the OpenWakeWord add-on and the wake word.
Speech-to-Text (STT): Select the Whisper service.
Text-to-Speech (TTS): Select the Piper service.
Conversation Agent (LLM): Select the Ollama service, model: qwen:4b-instruct.
- This is where you paste the instruction prompt for Qwen.

Instruction Prompt for Voice Assistant Settings on Home Assistant.

<Background Information>
You are a smart voice assistant for Home Assistant.
You know everything about my home devices and its states.
Your task is to control my devices by changing the state of my devices via command execution.
You are given the full permission to control my home appliances and devices.

<Instructions>
A user will provide a command to turn a device on or off.
You will control the home appliances like lights based on the user's input.
Below is the example conversation.

<Restrictions>
Don't give me the structured summary of current states.
Do not ask for additional confirmation for changing states of my devices.
Always respond in plain text only, no controlling characters, no emoji.
NEVER use emoji or any non-alphanumeric characters.
Keep the answer simple and to the point.

Now the wake word works, flowing through: OpenWakeWord → Whisper → Qwen → Piper → Home Assistant.

The Result

The outcome was surprisingly good. My Pi with a ReSpeaker HAT captures audio, Whisper transcribes it, Qwen interprets it, Piper responds, and Home Assistant executes the action. All fully offline.

Summary

Docker Desktop + Compose → perfect for auto-running Whisper and Piper.
Task Scheduler + Ollama Portable Zip → required for Intel Arc GPUs.
NVIDIA / Apple users → can just use the Ollama Desktop app.
IPEX-LLM on Arc A580 → makes Qwen 3-4B fast enough for real-time use.
Custom prompt → essential to keep responses clean and actionable.

What's Next

Run Whisper and Piper with GPU acceleration on the Intel Arc.
Try larger models with IPEX-LLM.
Improve intent handling for complex automations.
Add Japanese conversation support.