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
}

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

• 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:\\"
  ]
}

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"
}