Configuration Overview

DevEx uses a flexible, YAML-based configuration system that allows you to define your entire development environment declaratively. This guide covers all aspects of the configuration system, from basic concepts to advanced customization.

New to DevEx? Start with our Getting Started Guide first. For team configurations, see Team Setup Guide.

Configuration Architecture

applications.yaml

Define all installable applications, tools, and software

environment.yaml

Configure programming languages, fonts, and shells

desktop.yaml

Desktop environment themes, extensions, and settings

system.yaml

System-level settings like Git, SSH, and terminal

Configuration Locations

DevEx follows the XDG Base Directory Specification for configuration storage:

Directory Structure

~/.local/share/devex/config/   # Default configurations
├── applications.yaml           # Application definitions
├── environment.yaml           # Language and environment settings
├── desktop.yaml               # Desktop environment configuration
├── system.yaml                # System-level settings
└── templates/                 # Configuration templates
    ├── backend/
    ├── frontend/
    └── custom/

~/.devex/                      # User overrides (higher priority)
├── applications.yaml          # Override default applications
├── environment.yaml           # Custom environment settings
├── desktop.yaml              # Personal desktop preferences
└── system.yaml               # Personal system settings

~/.cache/devex/               # Cache directory
├── downloads/                # Downloaded packages
├── metadata/                 # Package metadata
└── repositories/             # Repository information

Configuration Priority

DevEx uses a layered configuration system with clear priority rules:

User Overrides (Highest Priority)

Files in ~/.devex/ override all other configurations:

# ~/.devex/applications.yaml
applications:
  development:
    - name: vscode
      extensions:
        - ms-python.python  # This overrides default extensions

Team/Template Configurations

Applied templates modify the base configuration:

devex template apply backend-team
# Applies team-specific settings

Default Configurations (Lowest Priority)

Built-in defaults in ~/.local/share/devex/config/:

# Default configuration shipped with DevEx

Configuration Syntax

All DevEx configuration files use YAML syntax with specific schema requirements.

Basic Structure

applications:
  development:
    - name: docker
      description: "Container platform"
      category: "Development Tools"
      default: true
      linux:
        install_method: apt
        install_command: docker-ce
      macos:
        install_method: brew
        install_command: docker
      windows:
        install_method: winget
        install_command: Docker.DockerDesktop

Cross-Platform Configuration

DevEx supports platform-specific configurations within the same file:

Platform Detection

# DevEx automatically detects:
# - Operating System: Linux, macOS, Windows
# - Distribution: Ubuntu, Fedora, Arch (Linux)
# - Architecture: x86_64, arm64
# - Desktop Environment: GNOME, KDE, XFCE (Linux)

Platform-Specific Settings

applications:
  development:
    - name: vscode
      # Common settings for all platforms
      description: "Visual Studio Code"
      category: "Development Tools"
      
      # Platform-specific installation
      linux:
        install_method: apt
        install_command: code
        apt_sources:
          - key_source: "https://packages.microsoft.com/keys/microsoft.asc"
          
      macos:
        install_method: brew
        install_command: visual-studio-code
        
      windows:
        install_method: winget
        install_command: Microsoft.VisualStudioCode

Configuration Validation

DevEx validates all configuration files before use:

DevEx automatically validates configuration files when:

Loading configurations during any command
Editing configuration files with devex config edit
Running devex config validate explicitly

Validation Rules

# Run validation
devex config validate

# Validation checks:
✓ YAML syntax correctness
✓ Required fields presence
✓ Value type correctness
✓ Cross-reference integrity
✓ Platform compatibility
✓ Dependency resolution

Common Validation Errors

# Invalid YAML
applications:
  development:
    - name: docker
    description: "Missing dash"  # Error: Wrong indentation

# Fix:
applications:
  development:
    - name: docker
      description: "Container platform"

Configuration Inheritance

DevEx supports configuration inheritance for complex scenarios:

Inheritance Chain

User Override (~/.devex/)
        ↓ (merges with)
Team Configuration (from template)
        ↓ (merges with)
Environment Configuration
        ↓ (merges with)
Default Configuration
        ↓
Final Effective Configuration

Merge Strategies

# Default configuration
applications:
  development:
    - name: git
    - name: curl

# User override (replace mode)
applications:  # Completely replaces default
  development:
    - name: git
    - name: docker

# Result: Only git and docker (curl removed)

Advanced Configuration Features

Variables and Templating

# Define variables
variables:
  user_name: "${USER}"
  home_dir: "${HOME}"
  config_dir: "${HOME}/.config"

# Use variables
applications:
  development:
    - name: custom-tool
      config_files:
        - source: "./configs/tool.conf"
          destination: "${config_dir}/tool/config"

Conditional Configuration

# Platform conditions
applications:
  development:
    - name: docker
      linux:
        when: "${DISTRO}" == "ubuntu"
        install_method: apt
      
      macos:
        when: "${ARCH}" == "arm64"
        install_method: brew
        install_command: docker-arm64

Configuration Fragments

# Include other configuration files
include:
  - ~/.devex/fragments/databases.yaml
  - ~/.devex/fragments/languages.yaml
  
# Or include from URLs
include:
  - https://company.com/configs/standard.yaml

Best Practices

Configuration Best Practices:

Keep configurations modular - Separate concerns into different files
Use version control - Track your configurations in Git
Document custom settings - Add comments explaining non-obvious configurations
Validate regularly - Run devex config validate after changes
Use templates for teams - Create reusable templates for consistency
Backup before major changes - Use devex config backup create

Configuration Management Workflow

Initial Setup

# Start with default configuration
devex setup

# Or apply a template
devex template apply backend

Customization

# Edit configurations
devex config edit applications

# Add specific tools
devex add docker postgresql

Validation

# Validate changes
devex config validate

# Test with dry-run
devex install --dry-run

Version Control

# Initialize Git repository
cd ~/.devex
git init
git add .
git commit -m "Initial DevEx configuration"

Sharing

# Export for team sharing
devex config export --output team-config.tar.gz

# Or create a template
devex template create team-backend

Configuration Examples

Minimal Configuration

# Minimal setup for basic development
applications:
  development:
    - name: git
    - name: curl
    - name: vim

programming_languages:
  - name: "Python"
    install_method: mise
    install_command: python@3.11

Full-Stack Configuration

# Complete full-stack development setup
applications:
  development:
    - name: git
    - name: docker
    - name: vscode
    - name: postman
  databases:
    - name: postgresql
    - name: redis
    - name: mongodb

programming_languages:
  - name: "Node.js LTS"
    install_method: mise
  - name: "Python 3.11"
    install_method: mise
  - name: "Go"
    install_method: mise

Troubleshooting Configuration Issues

# Check for syntax errors
devex config validate --verbose

# Auto-fix common issues
devex config validate --fix

# Validate specific file
devex config validate applications

Next Steps

Applications Configuration - Deep dive into application definitions
Environment Configuration - Programming languages and shells
Desktop Configuration - Themes and desktop environments
System Configuration - Git, SSH, and system settings
Templates Guide - Creating and using templates

The configuration system is the heart of DevEx. Understanding it well allows you to create powerful, reproducible development environments tailored to your exact needs.

Configuration Overview

Configuration OverviewCopy Anchor Link

Configuration ArchitectureCopy Anchor Link

applications.yaml

environment.yaml

desktop.yaml

system.yaml

Configuration LocationsCopy Anchor Link

Directory StructureCopy Anchor Link

Configuration PriorityCopy Anchor Link

Configuration SyntaxCopy Anchor Link

Basic StructureCopy Anchor Link

Cross-Platform ConfigurationCopy Anchor Link

Platform DetectionCopy Anchor Link

Platform-Specific SettingsCopy Anchor Link

Configuration ValidationCopy Anchor Link

Validation RulesCopy Anchor Link

Common Validation ErrorsCopy Anchor Link

Configuration InheritanceCopy Anchor Link

Inheritance ChainCopy Anchor Link

Merge StrategiesCopy Anchor Link

Advanced Configuration FeaturesCopy Anchor Link

Variables and TemplatingCopy Anchor Link

Conditional ConfigurationCopy Anchor Link

Configuration FragmentsCopy Anchor Link

Best PracticesCopy Anchor Link

Configuration Management WorkflowCopy Anchor Link

Configuration ExamplesCopy Anchor Link

Minimal ConfigurationCopy Anchor Link

Full-Stack ConfigurationCopy Anchor Link

Troubleshooting Configuration IssuesCopy Anchor Link

Next StepsCopy Anchor Link

On this page

Configuration Overview

Configuration Architecture

Configuration Locations

Directory Structure

Configuration Priority

Configuration Syntax

Basic Structure

Cross-Platform Configuration

Platform Detection

Platform-Specific Settings

Configuration Validation

Validation Rules

Common Validation Errors

Configuration Inheritance

Inheritance Chain

Merge Strategies

Advanced Configuration Features

Variables and Templating

Conditional Configuration

Configuration Fragments

Best Practices

Configuration Management Workflow

Configuration Examples

Minimal Configuration

Full-Stack Configuration

Troubleshooting Configuration Issues

Next Steps