Skip to content

aboylabs/ai-agent-skills / skills/creative/drawio-headless

drawio-headless

Verified

Generate architecture diagrams with draw.io in headless/server environments (WSL2, VPS, Docker)

---
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:**
```bash
# 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**
```bash
# 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

```bash
# 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

```bash
# 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:
```bash
# ❌ 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):**
```bash
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:**
```bash
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:
```bash
# 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:**
```bash
# ❌ 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

```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

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

### 3. Verify Output

```bash
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:**
```bash
# 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:
```bash
# 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
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 323kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall