Documenting the Chaos: Why I Switched to Excalidraw
Most HomeLabs start with a single Raspberry Pi running Pi-hole or a basic Plex server. It’s easy to manage. But then comes the Proxmox cluster, isolated IoT VLANs, and a stack of 30+ Docker containers. Suddenly, your mental map of the network collapses. During my first year, I relied on memory and frantic notebook scribbles. When my internal DNS went down at 2 AM, I wasn’t fixing the service—I was crawling under my desk tracing Ethernet cables to find the right gateway.
I tried heavy hitters like Lucidchart and Draw.io. They’re powerful, but they often felt too rigid for quick brainstorming or locked my data behind a login wall. Six months ago, I moved everything to a self-hosted Excalidraw instance on Docker. I wanted a tool that felt like a whiteboard but functioned like a digital architect’s desk. It has been rock solid. My documentation is now private, offline-capable, and—honestly—actually fun to draw.
The Architecture of a Self-Hosted Whiteboard
Excalidraw is a virtual whiteboard with a signature “hand-drawn” look. This isn’t just a gimmick. When a diagram looks like a sketch, you feel free to iterate. You stop obsessing over pixel-perfect alignment and start focusing on the actual logic. By hosting it locally, my sensitive network topology never touches a third-party cloud.
The standard Docker image serves the frontend. If you need multi-user collaboration, you can deploy the ‘room’ backend. For most of us, the standalone frontend is plenty. It’s fast, lightweight, and perfect for solo architects.
Installation: Deploying Excalidraw via Docker Compose
Docker Compose is my go-to for keeping configurations version-controlled. Below is the exact stack I’ve been running on my Ubuntu server. It’s simple, efficient, and pulls the latest stable builds automatically.
version: '3.8'
services:
excalidraw:
image: excalidraw/excalidraw:latest
container_name: excalidraw
ports:
- "3001:80"
restart: always
environment:
- NODE_ENV=production
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:80"]
interval: 30s
timeout: 10s
retries: 3
Fire it up with a quick docker-compose up -d and the UI is live at http://[SERVER-IP]:3001. The image is remarkably lean. Because it doesn’t rely on a heavy database, it snatches up very little disk space. There is one catch: by default, Excalidraw stores your work in the browser’s local storage. This makes the app snappy, but it means your diagrams aren’t truly “saved” until you export them to a file.
Refining the Configuration: Reverse Proxies and Custom Libraries
Typing IP addresses and ports is a hassle. To make it a permanent part of my workflow, I integrated it with Nginx Proxy Manager (NPM). I mapped draw.home.lan to the container and added an SSL certificate from my internal CA. Now, the connection is encrypted and the URL is easy to remember.
Importing HomeLab Icons
Standard circles and squares don’t cut it for a professional network map. You need servers, routers, and Wi-Fi icons. The secret sauce is libraries.excalidraw.com. I’ve customized my sidebar with several key sets:
- Cisco Network Icons: Essential for mapping managed switches and hardware firewalls.
- Cloud Infrastructure: Great for visualizing how local services talk to AWS or Cloudflare Tunnels.
- Software Architecture: Perfect for showing how Docker containers like Traefik or Authelia interact.
Once you import these, you can drag-and-drop a rack-mount server or a database icon onto your canvas in seconds.
Verification and Performance
After half a year of uptime, this container is one of the quietest residents in my stack. It typically idles at just 42MB of RAM and uses less than 1% of CPU cycles on an older i5 NUC. It’s the definition of “set it and forget it.”
If you want to check the pulse of the container, use:
docker logs -f excalidrawI also use Uptime Kuma to ping the URL every 60 seconds. In 180 days, I’ve had zero unplanned outages. The stability of the official image is impressive.
My Backup Strategy
Don’t trust your browser cache with your hard work. Every month, I export my master HomeLab map as an .excalidraw file and commit it to a private Gitea repository. This ensures that even if I clear my cookies or my laptop dies, my architecture is safe. You can also export as an SVG to embed your diagrams directly into a GitHub README or a Wiki.js page.
Final Thoughts
Self-hosting Excalidraw was one of the best administrative moves I’ve made. It bridges the gap between technical documentation and creative freedom. I no longer dread updating my network map because the tool is fast and the results look professional. If you’re tired of clunky enterprise software or the limitations of pen and paper, this Docker-based setup is a solid foundation for any growing HomeLab.
