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:

```json
{
  "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:
    ```json
    {
      "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:
   ```powershell
   # 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:

```json
{
  "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`:

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

```json
{
  "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)

```json
{
  "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"
}
```