drawio-headless

Files (4)

• SKILL.md
• electricity-consumption-analysis.md · references/
• system-services-diagram-pattern.md · references/
• vps-resource-diagram-pattern.md · references/

SKILL.md (first lines)

# 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)

From kevinnft/ai-agent-skills, MIT.

More from kevinnft/ai-agent-skills