docs/embedded_assets.md

📦 Embedded Assets for CUGA

This document explains how to use embedded assets to create a standalone CUGA server without requiring external frontend files.

🎯 Overview

CUGA can embed both the frontend (dist folder) and Chrome extension (chrome-mv3 folder) as compressed base64 data directly in the Python code. This eliminates the need to distribute hundreds of separate files and creates a more portable application.

🚀 Quick Start

Build with Embedded Assets

# Build and embed assets in one command
uv run scripts/build_embedded.py

This will:

1. 📦 Build the frontend (frontend-workspaces/frontend/dist)
2. 🔧 Build the extension (frontend-workspaces/extension/releases/chrome-mv3)
3. 📄 Embed both as base64 data in cuga/backend/server/embedded_assets.py

Run with Embedded Assets

# Enable embedded assets (disabled by default)
export USE_EMBEDDED_ASSETS=true
uv run cuga/backend/server/main.py

# Or run with embedded assets enabled in one command
USE_EMBEDDED_ASSETS=true uv run cuga/backend/server/main.py

# Run with file system assets (default behavior)
uv run cuga/backend/server/main.py

📁 File Structure

cuga/
├── backend/server/
│   ├── main.py              # Server with embedded assets support
│   └── embedded_assets.py   # Generated file with embedded data
scripts/
├── embed_assets.py          # Script to embed assets
└── build_embedded.py        # Complete build + embed workflow

🔧 How It Works

1. Feature Flag Control

• Embedded assets are disabled by default
• Controlled by USE_EMBEDDED_ASSETS environment variable
• Accepts: true, 1, yes, on (case-insensitive)

2. Asset Compression

• Frontend and extension folders are compressed into ZIP archives
• ZIP data is encoded as base64 strings
• Base64 strings are embedded in Python code

3. Runtime Extraction

• When enabled, assets are extracted to temporary directory
• Server uses extracted assets instead of file system paths
• Temporary files are cleaned up on shutdown

4. Fallback Support

• If embedded assets fail, falls back to file system paths
• Graceful degradation ensures compatibility

📊 Size Comparison

Component	Original Size	Compressed Size	Compression Ratio
Frontend	~44 MB	~9.4 MB	78% reduction
Extension	~12 MB	~7.7 MB	36% reduction
Total	~56 MB	~17 MB	70% reduction

🛠️ Manual Usage

Embed Assets Only

# Just embed existing built assets
uv run scripts/embed_assets.py

Build Assets Only

# Build frontend
cd frontend-workspaces
pnpm --filter "@carbon/ai-chat-examples-web-components-basic" run build

# Build extension
pnpm --filter extension run release

🔍 Advanced Configuration

Environment Variables

Variable	Default	Description
USE_EMBEDDED_ASSETS	false	Enable embedded assets. Accepts: true, 1, yes, on

# Examples of enabling embedded assets
export USE_EMBEDDED_ASSETS=true
export USE_EMBEDDED_ASSETS=1
export USE_EMBEDDED_ASSETS=yes
export USE_EMBEDDED_ASSETS=on

# Examples of disabling (default)
export USE_EMBEDDED_ASSETS=false
export USE_EMBEDDED_ASSETS=0
export USE_EMBEDDED_ASSETS=no
export USE_EMBEDDED_ASSETS=off
# Or simply don't set the variable

Custom Asset Paths

The embedded_assets.py file can be customized to change extraction behavior:

# Extract to specific directory
embedded_assets.temp_dir = Path("/custom/path")
frontend_path, extension_path = embedded_assets.extract_assets()

Compression Settings

Modify scripts/embed_assets.py to change compression:

# Change compression level
with zipfile.ZipFile(zip_buffer, 'w', zipfile.ZIP_DEFLATED, compresslevel=9) as zip_file:

🚀 Distribution Options

Option 1: Python Package with Embedded Assets

• Single Python package
• Assets embedded as base64 data
• ~23MB total size
• No external files needed

Option 2: Standalone Executable (Future)

# Build standalone executable (requires PyInstaller)
uv run scripts/build_standalone.py

🧹 Cleanup

Embedded assets are automatically cleaned up when the server shuts down. For manual cleanup:

from cuga.backend.server.embedded_assets import embedded_assets
embedded_assets.cleanup()

🐛 Troubleshooting

Assets Not Found

⚠️ Embedded assets not found, falling back to file system

Solution: Run uv run scripts/build_embedded.py to generate embedded assets.

Extraction Failed

❌ Failed to extract embedded assets: [error]

Solution: Check disk space and permissions in temp directory.

Large Memory Usage

The embedded base64 data is loaded into memory. For production deployments with memory constraints, consider using file system assets instead.

📈 Benefits

✅ Simplified Distribution: Single file deployment ✅ Reduced File Count: From hundreds of files to one ✅ Better Compression: 70% size reduction ✅ Faster Startup: No file system scanning ✅ Portable: Works without external dependencies

⚠️ Considerations

⚠️ Memory Usage: Assets loaded into memory ⚠️ Build Time: Longer initial build process ⚠️ Development: Requires rebuild after frontend changes

🔄 Development Workflow

For development, you can switch between embedded and file system assets:

# Force file system assets (for development)
USE_EMBEDDED_ASSETS = False

For production builds:

# Always build fresh embedded assets
uv run scripts/build_embedded.py