NoteDiscovery/documentation/ENVIRONMENT_VARIABLES.md

# 🔧 Environment Variables

NoteDiscovery supports environment variables to override configuration settings, allowing different behavior in different deployment environments (local, staging, production).

## 📋 Available Environment Variables

### Core Settings

| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `PORT` | integer | `8000` | HTTP port for the application (Docker, run.py) |

> **Note**: Advanced server settings (CORS origins, debug mode) are configured via `config.yaml` only, not via environment variables. See [config.yaml](#advanced-server-configuration) for details.

### Storage

| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `NOTES_DIR` | string | `./data` | Path to the notes vault |
| `PLUGINS_DIR` | string | `./plugins` | Path to the plugins directory |

The resolved paths are logged at startup so you can confirm what's in use:

```
INFO:     Notes directory: /home/me/MyVault (from NOTES_DIR env var)
INFO:     Plugins directory: ./plugins (from config.yaml)
```

#### Example: Pointing at an existing vault

```bash
# Local
NOTES_DIR=/home/me/MyVault python run.py

# Docker
docker run -e NOTES_DIR=/vault -v /home/me/MyVault:/vault ...
```

### Authentication

| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `AUTHENTICATION_ENABLED` | boolean | `config.yaml` | Enable/disable authentication |
| `AUTHENTICATION_PASSWORD` | string | `admin` | Password (hashed automatically at startup) |
| `AUTHENTICATION_SECRET_KEY` | string | `config.yaml` | Session secret key (for session security) |
| `AUTHENTICATION_API_KEY` | string | - | API key for external integrations (MCP, scripts) |

#### Example: Setting password via environment variable

```bash
# Docker
docker run -e AUTHENTICATION_ENABLED=true -e AUTHENTICATION_PASSWORD=mysecretpassword ...

# Docker Compose (in .env file or docker-compose.yml)
AUTHENTICATION_PASSWORD=mysecretpassword
```

### Demo Mode

| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `DEMO_MODE` | boolean | `false` | Enable demo mode (enables rate limiting and other demo restrictions) |

### Support

| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `ALREADY_DONATED` | boolean | `false` | Hides the support buttons in the Settings pane |

> ⚠️ **Disclaimer:** No verification exists. But legend says that setting this to `true` without donating causes your next `git push` to fail silently. Just once. When it matters most.
>
> Haven't donated yet? [☕ Buy me a coffee](https://ko-fi.com/gamosoft) - it takes 30 seconds and makes my day!

### Upload Limits

| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `UPLOAD_MAX_IMAGE_MB` | integer | `10` | Maximum image upload size in MB |
| `UPLOAD_MAX_AUDIO_MB` | integer | `50` | Maximum audio upload size in MB |
| `UPLOAD_MAX_VIDEO_MB` | integer | `100` | Maximum video upload size in MB |
| `UPLOAD_MAX_PDF_MB` | integer | `20` | Maximum PDF upload size in MB |

#### Example: Allowing larger video uploads

```bash
# Docker
docker run -e UPLOAD_MAX_VIDEO_MB=500 ...

# Docker Compose
environment:
  - UPLOAD_MAX_VIDEO_MB=500
```

### User Interface

| Variable | Type | Default | Description |
|----------|------|---------|-------------|
| `AUTOSAVE_DELAY_MS` | integer | `1000` | Autosave debounce in milliseconds (applies to note typing and drawing autosave). Server-clamped to 250–60000ms. |

#### Example: Slower autosave for very large notes

```bash
# Docker
docker run -e AUTOSAVE_DELAY_MS=5000 ...

# Docker Compose
environment:
  - AUTOSAVE_DELAY_MS=5000
```

Equivalent in `config.yaml`:

```yaml
ui:
  autosave_delay_ms: 5000
```

## 🎯 Configuration Priority

Configuration is loaded in this order (later overrides earlier):

1. **`config.yaml`** - Default configuration file
2. **Environment Variables** - Runtime overrides
3. **Command Line** - Highest priority (if applicable)

## 🔧 Advanced Server Configuration

The following settings are available in `config.yaml` only (not via environment variables):

### CORS (Cross-Origin Resource Sharing)

```yaml
server:
  # List of allowed origins for CORS
  # Default: ["*"] allows all origins (fine for self-hosted)
  # Production: specify your domains
  allowed_origins: ["*"]
  
  # Examples for production:
  # allowed_origins: ["http://localhost:8000", "https://yourdomain.com"]
  # allowed_origins: ["https://*.yourdomain.com"]  # Wildcard subdomain
```

**Security Note:**
- `["*"]` is **safe for self-hosted** deployments on private networks
- For **public deployments**, specify exact origins to prevent unauthorized API access
- This prevents CSRF attacks when authentication is enabled

### Debug Mode

```yaml
server:
  # Enable detailed error messages in API responses
  # Default: false (production-safe)
  # Set to true for development/troubleshooting
  debug: false
```

**⚠️ CRITICAL**: Never enable `debug: true` in production!

When `debug: true`:
- Full error stack traces are returned to users
- Internal paths and system details are exposed
- Security vulnerabilities may be revealed

When `debug: false` (recommended):
- Generic error messages are returned
- Full error details are logged server-side only
- Production-safe error handling

---

## 📚 Related Documentation

- **Authentication**: [AUTHENTICATION.md](AUTHENTICATION.md)
- **API Rate Limiting**: [API.md](API.md#rate-limiting)

---

**Pro Tip:** Use environment variables for **deployment-specific** settings, and `config.yaml` for **application defaults**. This keeps your configuration flexible and maintainable! 🎯