Deploying draw.io

Introduction

draw.io (also known as diagrams.net) is a powerful, open-source diagramming application that enables users to create professional diagrams directly in their web browser. Originally created by JGraph Ltd, draw.io has become one of the most popular diagramming tools available, offering a feature-rich alternative to commercial solutions like Microsoft Visio or Lucidchart.

The self-hosted version of draw.io provides all the functionality of the cloud-hosted service while giving you complete control over your data. Built as a static web application that can run entirely in the browser, draw.io requires no server-side processing for diagram creation, making it lightweight and easy to deploy.

Key highlights of draw.io:

• Comprehensive Diagram Types: Create flowcharts, network diagrams, UML diagrams, org charts, mind maps, floor plans, and more
• Extensive Shape Libraries: Access thousands of pre-built shapes including AWS, Azure, GCP, Cisco, and many other vendor-specific icons
• Multiple Export Formats: Export diagrams as PNG, JPEG, SVG, PDF, VSDX, HTML, and XML
• Real-Time Collaboration: Work together on diagrams with team members simultaneously
• Cloud Storage Integration: Connect to Google Drive, OneDrive, Dropbox, GitHub, and GitLab for diagram storage
• Offline Support: Continue working on diagrams even without an internet connection
• Customizable: Extend with custom shape libraries and templates
• Privacy-Focused: Your diagrams remain private when self-hosted
• 100% Open Source: Licensed under Apache 2.0 with no premium features locked behind paywalls

This guide walks through deploying draw.io on Klutch.sh using Docker, configuring the application for your organization’s needs, and setting up storage integrations.

Why Deploy draw.io on Klutch.sh

Deploying draw.io on Klutch.sh provides several advantages for your diagramming needs:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds draw.io without complex orchestration. Push to GitHub, and your diagramming application deploys automatically.

Data Privacy: Keep all your diagrams and intellectual property within your own infrastructure. No diagram data is sent to third-party servers.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your diagramming tool from anywhere without manual certificate management.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments, keeping your deployment in sync.

Custom Domains: Assign a custom domain to your draw.io instance for a professional, branded experience when sharing with your team.

Always-On Availability: Your diagramming tool remains accessible 24/7 without managing your own hardware or dealing with network configuration.

Resource Efficiency: draw.io is a lightweight static application, making it cost-effective to host on Klutch.sh.

Environment Variable Management: Configure storage integrations and customizations securely through Klutch.sh’s environment variable system.

Prerequisites

Before deploying draw.io on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your draw.io configuration
• Basic familiarity with Docker and containerization concepts
• (Optional) OAuth credentials for Google Drive, OneDrive, or other storage integrations
• (Optional) A custom domain for your draw.io instance

Understanding draw.io Architecture

draw.io is primarily a client-side application with optional server components:

Static Web Application: The core diagramming functionality runs entirely in the browser using JavaScript. The server simply delivers the static files, requiring minimal server resources.

Storage Backends: draw.io can connect to various storage services for saving and loading diagrams. This includes local browser storage, cloud services, and self-hosted options.

Export Server (Optional): For advanced export features like PDF generation with custom fonts, an optional server-side component can be deployed.

Real-Time Collaboration: When enabled, collaboration features use WebSocket connections for real-time updates between users.

Preparing Your Repository

To deploy draw.io on Klutch.sh, create a GitHub repository containing your Dockerfile and any custom configuration.

Repository Structure

drawio-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository. This example uses the official draw.io Docker image:

FROM jgraph/drawio:latest

# Optional: Set environment variables for configuration
ENV DRAWIO_SELF_CONTAINED=1
ENV DRAWIO_BASE_URL=${DRAWIO_BASE_URL}

# The base image exposes port 8080 by default
EXPOSE 8080

# The base image includes the default entrypoint

Advanced Dockerfile with Custom Configuration

For more control over your deployment, use this extended Dockerfile:

FROM jgraph/drawio:latest

# Enable self-contained mode for offline functionality
ENV DRAWIO_SELF_CONTAINED=1

# Set the base URL for your deployment
ENV DRAWIO_BASE_URL=${DRAWIO_BASE_URL}

# Optional: Configure Google Drive integration
ENV DRAWIO_GOOGLE_CLIENT_ID=${DRAWIO_GOOGLE_CLIENT_ID}
ENV DRAWIO_GOOGLE_APP_ID=${DRAWIO_GOOGLE_APP_ID}

# Optional: Configure OneDrive integration
ENV DRAWIO_MSGRAPH_CLIENT_ID=${DRAWIO_MSGRAPH_CLIENT_ID}

# Optional: Configure GitHub integration
ENV DRAWIO_GITHUB_CLIENT_ID=${DRAWIO_GITHUB_CLIENT_ID}

# Optional: Configure GitLab integration
ENV DRAWIO_GITLAB_ID=${DRAWIO_GITLAB_ID}
ENV DRAWIO_GITLAB_URL=${DRAWIO_GITLAB_URL}

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/ || exit 1

# Expose the application port
EXPOSE 8080

Creating the .dockerignore File

Create a .dockerignore file to exclude unnecessary files from the build:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

draw.io supports various environment variables for customization:

Variable	Required	Default	Description
DRAWIO_SELF_CONTAINED	No	0	Set to 1 to include all resources for offline use
DRAWIO_BASE_URL	No	-	Base URL for your draw.io instance
DRAWIO_CSP_HEADER	No	-	Custom Content Security Policy header
DRAWIO_VIEWER_URL	No	-	URL to the draw.io viewer for embedded diagrams
DRAWIO_GOOGLE_CLIENT_ID	No	-	Google OAuth client ID for Drive integration
DRAWIO_GOOGLE_APP_ID	No	-	Google App ID for Drive integration
DRAWIO_MSGRAPH_CLIENT_ID	No	-	Microsoft Graph client ID for OneDrive
DRAWIO_GITHUB_CLIENT_ID	No	-	GitHub OAuth client ID
DRAWIO_GITLAB_ID	No	-	GitLab OAuth application ID
DRAWIO_GITLAB_URL	No	-	Self-hosted GitLab URL

Deploying draw.io on Klutch.sh

Once your repository is prepared, follow these steps to deploy draw.io:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial draw.io deployment configuration"
git remote add origin https://github.com/yourusername/drawio-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “drawio” or “diagrams”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your draw.io Dockerfile.

Configure HTTP Traffic

draw.io serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8080 (draw.io’s default port)

Set Environment Variables

In the environment variables section, add any required configuration:

Variable	Value
DRAWIO_SELF_CONTAINED	1
DRAWIO_BASE_URL	https://your-app-name.klutch.sh

Add storage integration credentials if configuring cloud storage:

Variable	Value
DRAWIO_GOOGLE_CLIENT_ID	Your Google OAuth client ID
DRAWIO_GOOGLE_APP_ID	Your Google App ID

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Start the draw.io container
• Provision an HTTPS certificate

Access draw.io

Once deployment completes, access your draw.io instance at https://your-app-name.klutch.sh. You can immediately start creating diagrams.

Initial Setup and Configuration

Getting Started with draw.io

When you first access your draw.io instance:

1. Choose Storage Location: Select where to save your diagrams (Device, Browser, or connected cloud storage)
2. Create New Diagram: Click “Create New Diagram” to start from scratch or select a template
3. Open Existing: Open diagrams from your chosen storage location

Connecting Cloud Storage

Google Drive Integration

To enable Google Drive integration:

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Drive API and Google Picker API
4. Create OAuth 2.0 credentials (Web application type)
5. Add your draw.io URL to authorized JavaScript origins
6. Copy the Client ID and App ID to your environment variables
7. Redeploy your application

OneDrive Integration

To enable OneDrive integration:

1. Go to the Azure Portal
2. Register a new application in Azure Active Directory
3. Configure redirect URIs for your draw.io instance
4. Grant Microsoft Graph permissions for Files.ReadWrite
5. Copy the Application (client) ID to DRAWIO_MSGRAPH_CLIENT_ID
6. Redeploy your application

GitHub Integration

To enable GitHub integration:

1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Create a new OAuth application
3. Set the authorization callback URL to your draw.io instance
4. Copy the Client ID to DRAWIO_GITHUB_CLIENT_ID
5. Redeploy your application

Customizing Templates

Create custom templates for your organization:

1. Design your template diagram in draw.io
2. Export as XML
3. Host the template files on your server or configure them in the deployment
4. Reference templates in your configuration

Working with Diagrams

Supported Diagram Types

draw.io supports a wide variety of diagram types:

Category	Diagram Types
Business	Flowcharts, Org Charts, BPMN, Value Stream Maps
Software	UML, ERD, Sequence Diagrams, Class Diagrams
Network	Network Topology, Rack Diagrams, AWS/Azure/GCP Architecture
Engineering	Circuit Diagrams, Floor Plans, P&ID
General	Mind Maps, Venn Diagrams, Infographics

Shape Libraries

Access specialized shape libraries:

1. Click the ”+” button in the shapes panel
2. Browse available libraries by category
3. Enable libraries for AWS, Azure, GCP, Cisco, and more
4. Search for specific shapes using the search bar

Export Options

Export your diagrams in multiple formats:

Format	Use Case
PNG/JPEG	Web publishing, documentation
SVG	Scalable graphics, web embedding
PDF	Print-ready documents
VSDX	Microsoft Visio compatibility
XML	Backup, version control
HTML	Interactive web embedding

Real-Time Collaboration

Enabling Collaboration

draw.io supports real-time collaboration when connected to supported storage backends:

1. Google Drive: Share the diagram file with collaborators
2. OneDrive: Use standard OneDrive sharing
3. Confluence: Built-in collaboration through Confluence

Collaboration Features

• Real-Time Updates: See changes from other users instantly
• Cursor Tracking: View where other users are working
• Comments: Add comments to specific diagram elements
• Version History: Access previous versions of your diagram

Security Configuration

Content Security Policy

Configure a custom CSP header for enhanced security:

ENV DRAWIO_CSP_HEADER="default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; connect-src 'self' https://api.github.com https://graph.microsoft.com https://www.googleapis.com"

Access Control

For team deployments, consider implementing access control:

1. Use Klutch.sh’s authentication features if available
2. Deploy behind an authentication proxy like OAuth2 Proxy
3. Restrict access at the network level

Production Best Practices

Performance Optimization

• CDN Integration: Use a CDN for static assets to improve load times
• Compression: Enable gzip compression in your reverse proxy
• Caching: Configure appropriate cache headers for static files

Backup Strategy

Protect your diagram data:

1. Cloud Storage Backups: Diagrams stored in Google Drive, OneDrive, or GitHub are backed up by those services
2. Export Regularly: Periodically export important diagrams as XML for local backup
3. Version Control: Store diagram XML files in Git repositories for version history

Monitoring

Monitor your draw.io deployment:

1. Klutch.sh Dashboard: View deployment health and logs
2. Health Checks: The configured health check ensures container availability
3. Usage Analytics: Consider adding privacy-respecting analytics if needed

Troubleshooting Common Issues

Application Won’t Load

Symptoms: Blank page or loading spinner that never completes.

Solutions:

• Clear browser cache and cookies
• Check browser console for JavaScript errors
• Verify the deployment is running in Klutch.sh dashboard
• Ensure port 8080 is correctly configured

Cloud Storage Connection Failed

Symptoms: Unable to connect to Google Drive, OneDrive, or other storage.

Solutions:

• Verify OAuth credentials are correctly configured
• Check that redirect URIs match your deployment URL
• Ensure required API permissions are granted
• Review browser console for authentication errors

Diagrams Not Saving

Symptoms: Changes are lost when closing the browser.

Solutions:

• Verify storage backend is properly configured
• Check browser storage permissions
• Use “Save As” to explicitly save to desired location
• Clear browser cache and try again

Export Features Not Working

Symptoms: PDF or other exports fail or produce incorrect output.

Solutions:

• Ensure the export server component is deployed if needed
• Check that all required fonts are available
• Try exporting to a different format
• Use the PNG export as a fallback

Performance Issues

Symptoms: Slow diagram loading or editing.

Solutions:

• Reduce diagram complexity
• Break large diagrams into smaller linked diagrams
• Clear browser cache
• Allocate additional resources if needed

Updating draw.io

To update to a newer version of draw.io:

1. Review Release Notes: Check the draw.io releases for changes
2. Update Dockerfile: If pinning to a specific version, update the tag
3. Push Changes: Commit and push to trigger redeployment
4. Verify: Test diagram creation and storage integrations

draw.io follows semantic versioning, and updates are generally backward compatible.

Additional Resources

• Official draw.io Website
• draw.io Documentation
• draw.io GitHub Repository
• draw.io Docker Repository
• draw.io Blog
• draw.io Support
• Klutch.sh Deployments

Conclusion

Deploying draw.io on Klutch.sh gives you a powerful, self-hosted diagramming solution with automatic builds, secure HTTPS access, and complete control over your data. The combination of draw.io’s feature-rich interface and Klutch.sh’s deployment simplicity means you can focus on creating professional diagrams rather than managing infrastructure.

With support for multiple diagram types, extensive shape libraries, and integration with popular cloud storage services, draw.io on Klutch.sh provides a comprehensive diagramming platform for individuals and teams. Whether you’re creating simple flowcharts or complex cloud architecture diagrams, draw.io delivers the tools you need with the privacy and control of self-hosting.