Architecture overview
DisplayGrid has two distinct hardware roles:
- Server: runs the Next.js dashboard and WebSocket server. Needs to be always-on and reachable by all display devices on the network.
- Display client: runs a browser in kiosk mode. Can be any device from a Raspberry Pi to an old laptop.
For a single-screen setup, both roles can run on the same machine. For larger deployments, dedicate a separate server so display clients don't compete for resources.
Server hardware
Minimum
| Component | Specification |
|---|---|
| Device | Raspberry Pi 4 (2 GB RAM) |
| OS | Raspberry Pi OS Lite, Ubuntu Server, any Linux distro |
| Storage | 16 GB microSD (Class 10 / A1) |
| Network | Wired Ethernet recommended |
Recommended
| Component | Specification |
|---|---|
| Device | Raspberry Pi 5 (4 GB+) or any x86 mini PC |
| OS | Raspberry Pi OS, Ubuntu, Windows, macOS |
| Storage | 32 GB+ USB SSD or NVMe (Pi 5 supports NVMe via HAT) |
| Cooling | Active cooling required for Pi 5 under sustained load |
| Network | Gigabit Ethernet |
Pi 5 tip: Use the official Raspberry Pi Active Cooler or a third-party heatsink with fan. The Pi 5 throttles under sustained load without active cooling, which can cause WS latency spikes.
Mini PC alternatives
Any always-on mini PC works well as a server. Popular choices include Intel NUC, Beelink, Minisforum, and ASUS NUC units. These offer faster storage, more RAM, and better thermal performance than a Pi, which is useful when serving many screens or large video assets.
Display client hardware
The display client runs in a standard browser. Any device that can run Chrome or Chromium is suitable.
| Device | Best for | Notes |
|---|---|---|
| Raspberry Pi 5 (4 GB+) | 4K images, 1080p video, web content | Recommended for video-heavy playlists |
| Raspberry Pi 4 (2 GB) | 1080p images, simple web slides | Struggles with 4K or complex video |
| Intel NUC / mini PC | Any resolution, any content type | Most reliable for demanding content |
| Old laptop (2015+) | 1080p images and video | Good for repurposing existing hardware |
| Mac mini | Any resolution | Excellent performance, higher cost |
| Android TV stick | Basic image slideshows | Use Chromium via ADB; limited video support |
Video performance: Video playback is handled entirely by the browser's hardware decoder. Raspberry Pi 4 can play 1080p H.264 smoothly but may drop frames on H.265 or 4K. Use the Pi 5 or an x86 device for video-heavy deployments.
Running on one machine
For a single-screen setup or development, you can run the server and display client on the same machine. The display client connects to the local server at http://localhost:3000 and ws://localhost:3001.
This works well on a Raspberry Pi 5 or any desktop/laptop. On a Pi 4, resource contention between the server and browser may cause occasional stuttering on video content.
Storage recommendations
All uploaded assets are stored on the server's disk. Plan for storage based on your content:
- Images only: 16 GB is more than enough. Images are compressed to WebP on upload.
- Mixed images and video: 64 GB minimum. A 1-minute 1080p MP4 is typically 100-300 MB.
- Heavy video library: use an external USB SSD or network-attached storage.
For Raspberry Pi deployments, avoid cheap microSD cards for the server as they fail under sustained write load. Use a USB SSD or the NVMe HAT for Pi 5.
Networking
DisplayGrid uses standard HTTP and WebSocket (port 3001). No special network configuration is needed for a basic deployment where all devices are on the same subnet.
- Use wired Ethernet for the server if possible, as Wi-Fi adds latency and increases the chance of WS disconnects.
- Display clients can use Wi-Fi without issue. The WS connection auto-reconnects if the network drops.
- For cross-VLAN deployments, see the Network guide.