drawio-headless

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