/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:**

• dr