How to: Use multiple config files

YAML Anchoring Configuration Examples

This document explains how to use YAML anchoring with the multi-file configuration system.

How It Works

The main config file uses YAML merge keys (<<:) to include anchored configurations from separate modular files:

• server-config.yaml - Server settings (port, sources, logging)
• auth-config.yaml - Authentication configuration
• integrations-config.yaml - Media and office integration settings
• frontend-config.yaml - UI styling and themes
• users-config.yaml - User default settings

Basic Concepts

1. Anchor Definition (&anchor_name)

Define a reusable configuration block with a name.

2. Alias Reference (*anchor_name)

Reference the entire anchor exactly as defined.

3. Merge Key (<<: *anchor_name)

Merge the anchor into the current context, allowing overrides.

---

Key Benefit: Quick Configuration Switching

The power of YAML anchoring is that you can switch entire configuration profiles by changing just one line in your main config file.

Example: Switch from development to production by changing the anchor reference:

# config.yaml - Switch environments by changing the anchor name

# For development:
server:
  <<: *server_dev

# For production (just change the anchor name):
server:
  <<: *server_production

This lets you:

• Maintain multiple configuration presets in separate files
• Switch between them instantly
• Override specific fields when needed
• Keep your main config file clean and simple

---

Example 1: Server Configurations with Quick Switching

File: server-config.yaml

# Development server - multiple sources, verbose logging
server_dev: &server_dev
  port: 8080
  baseURL: "/dev"
  logging:
    - levels: "info|debug|warning|error"
  sources:
    - path: "/data/downloads"
      name: "downloads"
      config:
        defaultEnabled: true

    - path: "/data/projects"
      name: "projects"
      config:
        private: false
        disableIndexing: false

    - path: "/media/movies"
      name: "movies"

# Production server - restricted sources, minimal logging
server_production: &server_production
  port: 80
  baseURL: "/"
  logging:
    - levels: "warning|error"
  sources:
    - path: "/data/public"
      name: "public"
      config:
        private: false
        denyByDefault: false

# Minimal server - single source
server_minimal: &server_minimal
  port: 8080
  baseURL: "/"
  sources:
    - path: "/data"

File: config.yaml

# Simply change the anchor name to switch configurations!
server:
  <<: *server_dev              # Use development config
  # <<: *server_production     # OR use production config
  # <<: *server_minimal        # OR use minimal config

To switch environments: Just uncomment the line you want and comment out the others!

---

Example 2: User Permission Presets

File: users-config.yaml

# Admin user - full permissions
user_admin: &user_admin
  showHidden: true
  permissions:
    admin: true
    modify: true
    share: true
    api: true
  preview:
    office: true
    video: true
    popup: true

# Regular user - standard permissions
user_regular: &user_regular
  showHidden: false
  permissions:
    admin: false
    modify: true
    share: true
    api: false

# Read-only user - view only
user_readonly: &user_readonly
  showHidden: false
  permissions:
    admin: false
    modify: false
    share: false
    api: false
  lockPassword: true

File: config.yaml

# Switch default user permissions with one line!
userDefaults:
  <<: *user_regular            # Use regular user settings
  # <<: *user_admin            # OR use admin settings
  # <<: *user_readonly         # OR use readonly settings

---

Extending Anchors

You can also extend an anchor and add/override specific fields:

File: server-config.yaml

server_base: &server_base
  port: 80
  baseURL: "/"
  sources:
    - path: "/data"

# Extend base and add search length
server_extended: &server_extended
  <<: *server_base             # Include everything from server_base
  minSearchLength: 10          # Add new field

File: config.yaml

# Use extended config but override the port
server:
  <<: *server_extended
  port: 8080                   # Override just this one field

---

Complete Multi-File Setup

Here's how to structure your complete configuration:

File: config.yaml (Main config - minimal and clean!)

server:
  <<: *server_dev

auth:
  <<: *auth_oidc

integrations:
  <<: *integrations_full

userDefaults:
  <<: *user_regular

frontend:
  <<: *frontend_multi_theme

To deploy to production: Change the anchor references:

server:
  <<: *server_production       # Changed from *server_dev

auth:
  <<: *auth_oidc

integrations:
  <<: *integrations_no_office  # Changed from *integrations_full

userDefaults:
  <<: *user_readonly           # Changed from *user_regular

frontend:
  <<: *frontend_single_theme   # Changed from *frontend_multi_theme

---

Benefits

1. One-line switching: Change entire configuration profiles by modifying one anchor name
2. Modularity: Each concern lives in its own file
3. Reusability: Create multiple presets and reuse them across environments
4. Maintainability: Update one anchor to affect all configs that use it
5. Clean main config: Your main config file stays simple and readable
6. Testing: Quickly test different configurations without duplicating code

Validation

All configurations must match the structure defined in config.generated.yaml. The anchor system just provides a way to organize and reuse configuration blocks.