drawio-headless

name	drawio-headless
description	Generate architecture diagrams with draw.io in headless/server environments (WSL2, VPS, Docker)
version	1.0.0
dependencies	["draw.io desktop (snap or .deb)","xvfb (X virtual framebuffer)"]
platforms	["linux"]
tags	["diagrams","architecture","visualization","headless","wsl2"]
origin	unknown
source_license	see upstream
language	en

Draw.io Headless Diagram Generation

Generate professional architecture diagrams from .drawio XML files in headless environments (WSL2, VPS, Docker) where GUI is not available.

When to Use

• Server/VPS without X11 display
• WSL2 Ubuntu (no native GUI)
• Docker containers
• CI/CD pipelines
• Automated diagram generation

Prerequisites

Required packages:

# Install draw.io (snap - easiest)
sudo snap install drawio

# Install Xvfb (virtual framebuffer for headless rendering)
sudo apt-get update
sudo apt-get install -y xvfb

Alternative: .deb package

# Download latest .deb
wget https://github.com/jgraph/drawio-desktop/releases/download/v28.2.5/drawio-amd64-28.2.5.deb

# Install
sudo dpkg -i drawio-amd64-28.2.5.deb
sudo apt-get install -f  # Fix dependencies

Verification

# Check draw.io installation
which drawio
# Expected: /snap/bin/drawio or /usr/bin/drawio

# Test with xvfb-run
xvfb-run -a drawio --version
# Expected: draw.io version number (e.g., 28.2.5)

Usage

Basic Export

# Export .drawio to PNG
xvfb-run -a drawio -x -f png -o output.png input.drawio

# Export to SVG
xvfb-run -a drawio -x -f svg -o output.svg input.drawio

# Export to PDF
xvfb-run -a drawio -x -f pdf -o output.pdf input.drawio

Flags Explained

• xvfb-run -a — Run in virtual framebuffer (headless)
• -x — Export mode
• -f <format> — Output format (png, svg, pdf, jpg)
• -o <output> — Output file path
• <input> — Input .drawio file

Pitfalls

1. Snap Confinement (File Access)

Problem: Snap-installed draw.io cannot access /tmp or arbitrary directories due to confinement.

Solution: Use home directory or snap-accessible paths:

# ❌ FAILS (snap cannot access /tmp)
xvfb-run -a drawio -x -f png -o /tmp/diagram.png /tmp/input.drawio

# ✅ WORKS (home directory accessible)
cd ~/diagrams
xvfb-run -a drawio -x -f png -o diagram.png input.drawio

Snap-accessible paths:

• ~/ (home directory)
• /home/<user>/
• /media/ (removable media)
• /mnt/ (mounted filesystems)

2. OpenGL/dbus Warnings

Symptoms: Errors like:

libGL error: No matching fbConfigs or visuals found
dbus[]: Failed to connect to socket

Impact: These are warnings only — export still succeeds. Safe to ignore in headless environments.

Suppress (optional):

xvfb-run -a drawio -x -f png -o output.png input.drawio 2>/dev/null

3. Missing Xvfb

Symptom:

Error: Cannot open display: :99

Fix:

sudo apt-get install -y xvfb

4. Large Diagrams (Memory)

Problem: Complex diagrams with many elements may consume significant memory.

Solution: Monitor memory usage, increase if needed:

# Check available memory before export
free -h

# For very large diagrams, consider SVG (vector, smaller memory footprint)
xvfb-run -a drawio -x -f svg -o output.svg input.drawio

5. Premature Deletion (CRITICAL)

Problem: Deleting diagram files immediately after generation but before user confirms receipt.

Symptom: User reports "diagram not received" but files already deleted.

Root cause: Telegram/messaging platforms may have delivery lag. Deleting before send confirmation = data loss.

Solution:

# ❌ WRONG — Delete immediately after MEDIA: path returned
xvfb-run -a drawio -x -f png -o diagram.png diagram.drawio
echo "MEDIA:/path/to/diagram.png"
rm diagram.png diagram.drawio  # TOO EARLY!

# ✅ CORRECT — Keep files, cleanup weekly
xvfb-run -a drawio -x -f png -o ~/diagrams/analysis_$(date +%Y%m%d).png diagram.drawio
echo "MEDIA:~/diagrams/analysis_20260505.png"
# Files remain for user reference

# Weekly cleanup (manual or cron)
find ~/diagrams -name "*.png" -mtime +7 -delete

Policy: Never auto-delete diagrams after sending. User may need to reference them later or delivery may fail silently.

Diagram Types Supported

• Architecture diagrams (microservices, cloud, infrastructure)
• Flowcharts (process flows, decision trees)
• Sequence diagrams (API calls, interactions)
• Network diagrams (topology, connections)
• ER diagrams (database schemas)
• UML diagrams (class, component, deployment)

Example Workflow

1. Create .drawio XML

<mxfile host="app.diagrams.net">
  <diagram name="Example">
    <mxGraphModel dx="1200" dy="900">
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
        
        <!-- Add your diagram elements here -->
        <mxCell id="box1" value="Service A" 
                style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;" 
                vertex="1" parent="1">
          <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
        </mxCell>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

2. Export to PNG

xvfb-run -a drawio -x -f png -o diagram.png diagram.drawio

3. Verify Output

ls -lh diagram.png
file diagram.png
# Expected: PNG image data, ...

Integration with Hermes

When generating diagrams in Hermes workflows:

1. Create .drawio XML programmatically (Python, script, template)
2. Export via xvfb-run in execute_code or terminal tool
3. Return path via MEDIA:/path/to/diagram.png for Telegram
4. DO NOT auto-delete — Keep diagrams for user reference (cleanup weekly, not per-send)

Performance

Typical export times:

• Simple diagram (5-10 elements): 2-3 seconds
• Medium diagram (20-50 elements): 4-6 seconds
• Complex diagram (100+ elements): 8-12 seconds

Memory usage:

• draw.io process: ~100-200 MB during export
• Xvfb overhead: ~10-20 MB

Troubleshooting

Export produces blank/empty PNG

Cause: Invalid XML structure or missing geometry.

Fix: Validate .drawio XML structure, ensure all cells have geometry.

"Command not found: drawio"

Cause: Snap bin directory not in PATH.

Fix:

# Add to ~/.bashrc
export PATH="/snap/bin:$PATH"

# Or use full path
xvfb-run -a /snap/bin/drawio -x -f png -o output.png input.drawio

Permission denied

Cause: Output directory not writable or snap confinement.

Fix: Use home directory or check permissions:

# Use home directory
cd ~/diagrams

# Or check permissions
ls -ld /path/to/output/directory

References

• references/system-services-diagram-pattern.md — Pattern for mapping running services to comprehensive diagrams
• references/electricity-consumption-analysis.md — Household/office electricity analysis with AC-focused breakdown and savings scenarios

See Also

• architecture-diagram skill — Dark-themed SVG architecture diagrams as HTML
• excalidraw skill — Hand-drawn style diagrams (JSON format)
• draw.io GitHub: https://github.com/jgraph/drawio-desktop