webdrop-bridge/CONFIG_README.md

WebDrop Bridge Configuration Guide

Configuration File Location

WebDrop Bridge supports two configuration methods:

1. JSON Configuration File (Recommended for Azure URL mapping)

   • Windows: %APPDATA%\webdrop_bridge\config.json
   • macOS/Linux: ~/.config/webdrop_bridge/config.json

2. Environment Variables (.env file in project root)

   • Used as fallback if JSON config doesn't exist

JSON Configuration Format

Create a config.json file with the following structure:

{
  "app_name": "WebDrop Bridge",
  "webapp_url": "https://dev.agravity.io/",
  "url_mappings": [
    {
      "url_prefix": "https://devagravitystg.file.core.windows.net/devagravitysync/",
      "local_path": "Z:"
    }
  ],
  "allowed_roots": [
    "Z:\\"
  ],
  "allowed_urls": [],
  "check_file_exists": true,
  "auto_check_updates": true,
  "update_check_interval_hours": 24,
  "log_level": "INFO",
  "log_file": "logs/webdrop_bridge.log",
  "window_width": 1024,
  "window_height": 768,
  "enable_logging": true,
  "language": "auto",
  "active_branding_id": "default",
  "brand_id": "agravity"
}

Configuration Options

Core Settings

• webapp_url (string): URL of the web application to load

  • Example: "https://dev.agravity.io/"
  • Supports http://, https://, or file:/// URLs

• url_mappings (array): Azure Blob Storage URL to local path mappings

  • Each mapping has:
    • url_prefix: Azure URL prefix (must end with /)
    • local_path: Local drive letter or path
  • Example:

    {
      "url_prefix": "https://dev.file.core.windows.net/devagravitysync/",
      "local_path": "Z:"
    }
    

• allowed_roots (array): Whitelisted root directories for file access

  • Security feature: Only files within these directories can be dragged
  • Example: ["Z:\\", "C:\\Users\\Public"]

Azure URL Mapping Example

When the web application provides a drag URL like:

https://devagravitystg.file.core.windows.net/devagravitysync/aN5PysnXIuRECzcRbvHkjL7g0/Hintergrund_Agravity.png

It will be converted to:

Z:\aN5PysnXIuRECzcRbvHkjL7g0\Hintergrund_Agravity.png

Security Settings

• check_file_exists (boolean): Validate files exist before allowing drag

  • Default: true
  • Set to false only for testing

• allowed_urls (array): Allowed URL patterns for web content

  • Empty array = no restriction
  • Example: ["dev.agravity.io", "*.example.com"]

Update Settings

• auto_check_updates (boolean): Automatically check for updates on startup

  • Default: true

• update_check_interval_hours (number): Hours between update checks

  • Default: 24

UI Settings

• window_width, window_height (number): Initial window size in pixels
  • Default: 1024 x 768

Language and Branding Settings

• language (string): UI language code

  • Use "auto" to follow the system locale automatically
  • Bundled translations currently include en, de, fr, it, ru, and zh

• active_branding_id (string): Runtime branding template selected in the Settings dialog

  • Default: "default"
  • Useful when switching between saved branding templates without rebuilding the app

• brand_id (string): Stable packaging/update identifier for branded variants

  • Usually injected during packaging and normally left unchanged by end users

• log_level (string): Logging verbosity

  • Options: "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
  • Default: "INFO"

• log_file (string, optional): Path to log file

  • If null or not specified: Logs to %APPDATA%\webdrop_bridge\logs\webdrop_bridge.log (Windows) or ~/.local/share/webdrop_bridge/logs/webdrop_bridge.log (macOS/Linux)
  • If relative path: Resolved relative to the app data directory (same as above location)
  • If absolute path: Used as-is
  • Default: null (uses AppData directory for permissions compatibility)
  • ℹ️ Important: Logs are always stored in the user's AppData directory to ensure the app can write logs in both development and installed scenarios

• enable_logging (boolean): Whether to write logs to file

  • Default: true

Quick Start

1. Copy config.example.json to your config directory:

   # Windows
   mkdir "$env:APPDATA\webdrop_bridge"
   copy config.example.json "$env:APPDATA\webdrop_bridge\config.json"
   

2. Edit the configuration file with your Azure URL mappings and local paths

3. Restart WebDrop Bridge

Multiple URL Mappings

You can configure multiple Azure storage accounts:

{
  "url_mappings": [
    {
      "url_prefix": "https://storage1.file.core.windows.net/container1/",
      "local_path": "Z:"
    },
    {
      "url_prefix": "https://storage2.file.core.windows.net/container2/",
      "local_path": "Y:"
    }
  ],
  "allowed_roots": [
    "Z:\\",
    "Y:\\"
  ]
}

Configuration Priority

At startup, WebDrop Bridge first loads any bootstrap .env defaults and then prefers the persisted JSON config if it exists. This means:

1. packaged or development defaults can still come from .env,
2. the Settings dialog saves the active runtime configuration to JSON, and
3. the JSON file becomes the main configuration source after first save.

Environment Variable Fallback

If no JSON config exists, WebDrop Bridge will load from .env:

APP_NAME=WebDrop Bridge
WEBAPP_URL=https://dev.agravity.io/
ALLOWED_ROOTS=Z:/
LOG_LEVEL=INFO
WINDOW_WIDTH=1024
WINDOW_HEIGHT=768

Note: Environment variables don't support url_mappings. Use JSON config for Azure URL mapping.

Troubleshooting

"No mapping found for URL"

• Check that url_prefix matches the Azure URL exactly (including trailing /)
• Verify url_mappings is configured in your JSON config file
• Check logs in logs/webdrop_bridge.log

"Path is not within allowed roots"

• Ensure the mapped local path (e.g., Z:) is listed in allowed_roots
• Make sure the drive is mounted and accessible

"File does not exist"

• Verify the Azure sync is working and files are available locally
• Set check_file_exists: false temporarily for testing
• Check that the path mapping is correct

Example Configurations

Production (Agravity DEV)

{
  "webapp_url": "https://dev.agravity.io/",
  "url_mappings": [
    {
      "url_prefix": "https://devagravitystg.file.core.windows.net/devagravitysync/",
      "local_path": "Z:"
    }
  ],
  "allowed_roots": ["Z:\\"],
  "log_level": "INFO"
}

Development (Local Testing)

{
  "webapp_url": "file:///./webapp/index.html",
  "url_mappings": [
    {
      "url_prefix": "https://test.blob.core.windows.net/test/",
      "local_path": "C:\\temp\\test"
    }
  ],
  "allowed_roots": ["C:\\temp\\test"],
  "check_file_exists": false,
  "log_level": "DEBUG"
}