Desktop Configuration

The desktop.yaml file manages desktop environment configurations including GUI applications, themes, settings, extensions, and visual customizations. This ensures consistent desktop experiences across different machines.

File Location

# Default configuration
~/.local/share/devex/config/desktop.yaml

# User override (higher priority)
~/.devex/desktop.yaml

File Structure

desktop_applications:
  productivity:          # Application categories
    - name: string       # Application name
      description: string # Application description
      category: string   # Application category
      # Platform-specific configs...
      
  development:
    # Development GUI applications
    
  multimedia:
    # Media applications

Desktop Applications

DevEx manages GUI applications that require desktop environments, providing cross-platform installation support.

Application Schema

Field	Type	Required	Description
`name`	`string`	Yes	Application identifier
`description`	`string`	Yes	Human-readable description
`category`	`string`	Yes	Application category
`desktop_environments`	`string[]`	No	Supported DEs
`linux`	`object`	No	Linux installation config
`macos`	`object`	No	macOS installation config
`windows`	`object`	No	Windows installation config

Platform-Specific Configuration

desktop_applications:
  productivity:
    - name: LocalSend
      description: 'Cross-platform secure file sharing'
      category: 'File Sharing'
      desktop_environments: ['all']
      
      linux:
        # Primary installation method
        install_method: 'flatpak'
        install_command: 'flatpak install flathub org.localsend.localsend_app'
        uninstall_command: 'flatpak remove org.localsend.localsend_app'
        official_support: true
        dependencies:
          - 'flatpak'
          
        # Alternative installation methods
        alternatives:
          - install_method: 'snap'
            install_command: 'localsend'
            uninstall_command: 'localsend'
            official_support: true
            
          - install_method: 'yay'  # AUR helper
            install_command: 'localsend-bin'
            uninstall_command: 'localsend-bin'
            official_support: false

Application Categories

Productivity

File sharing, office suites, note-taking

Development

IDEs, GUI development tools

Multimedia

Media players, editors, streaming

Communication

Chat, video calls, email

Desktop Environment Specific Configuration

DevEx supports desktop environment-specific configurations including themes, extensions, and settings.

GNOME Configuration

# Separate gnome.yaml configuration
platforms: ["linux"]

themes:
  - name: 'Tokyo Night'
    theme_color: 'purple'
    theme_background: 'assets/themes/tokyo-night/background.jpg'
    neovim_colorscheme: 'assets/themes/tokyo-night/neovim.lua'
    
  - name: 'Kanagawa'
    theme_color: 'purple'
    theme_background: 'assets/themes/kanagawa/background.jpg'
    neovim_colorscheme: 'assets/themes/kanagawa/neovim.lua'

settings:
  - name: 'Tweaks'
    settings:
      - key: 'org.gnome.mutter center-new-windows'
        value: true
        
  - name: 'Monospace Font'
    settings:
      - key: 'org.gnome.desktop.interface monospace-font-name'
        value: 'CaskaydiaMono Nerd Font 10'

extensions:
  - id: 'tactile@lundal.io'
    schema_files:
      - source: '~/.local/share/gnome-shell/extensions/tactile@lundal.io/schemas/org.gnome.shell.extensions.tactile.gschema.xml'
        destination: '/usr/share/glib-2.0/schemas/'
        
dock:
  - name: 'VS Code'
    desktop_file: 'code.desktop'
  - name: 'Settings'
    desktop_file: 'org.gnome.Settings.desktop'

GNOME Settings Configuration

settings:
  - name: 'Window Behavior'
    settings:
      # Center new windows
      - key: 'org.gnome.mutter center-new-windows'
        value: true
        
      # Window management keybindings
      - key: 'org.gnome.desktop.wm.keybindings close'
        value: "['<Super>w']"
        
      - key: 'org.gnome.desktop.wm.keybindings maximize'
        value: "['<Super>Up']"
        
      - key: 'org.gnome.desktop.wm.keybindings begin-resize'
        value: "['<Super>BackSpace']"

Theme Management

Theme Definition: Configure visual themes with backgrounds and color schemes

Application Integration: Link themes to specific applications (Neovim, terminals)

Asset Management: Organize theme assets (wallpapers, color files)

Theme Switching: Enable easy switching between predefined themes

themes:
  - name: 'Tokyo Night'
    theme_color: 'purple'
    theme_background: 'assets/themes/tokyo-night/background.jpg'
    neovim_colorscheme: 'assets/themes/tokyo-night/neovim.lua'
    terminal_theme: 'assets/themes/tokyo-night/terminal.json'
    vscode_theme: 'Tokyo Night'
    
  - name: 'Gruvbox'
    theme_color: 'orange'
    theme_background: 'assets/themes/gruvbox/background.jpg'
    neovim_colorscheme: 'assets/themes/gruvbox/neovim.lua'
    terminal_theme: 'assets/themes/gruvbox/terminal.json'
    vscode_theme: 'Gruvbox Dark Hard'

  - name: 'Catppuccin'
    theme_color: 'pink'
    theme_background: 'assets/themes/catppuccin/background.jpg'
    neovim_colorscheme: 'assets/themes/catppuccin/neovim.lua'
    terminal_theme: 'assets/themes/catppuccin/terminal.json'
    vscode_theme: 'Catppuccin Mocha'

Real-World Configuration Examples

Productivity-Focused Setup

desktop_applications:
  productivity:
    - name: LocalSend
      description: 'Secure file sharing across devices'
      category: 'File Sharing'
      desktop_environments: ['all']
      
      linux:
        install_method: 'flatpak'
        install_command: 'flatpak install flathub org.localsend.localsend_app'
        uninstall_command: 'flatpak remove org.localsend.localsend_app'
        
    - name: Obsidian
      description: 'Knowledge management and note-taking'
      category: 'Productivity'
      
      linux:
        install_method: 'flatpak'
        install_command: 'flatpak install flathub md.obsidian.Obsidian'
        
      macos:
        install_method: 'brew'
        install_command: '--cask obsidian'
        
      windows:
        install_method: 'winget'
        install_command: 'Obsidian.Obsidian'

  communication:
    - name: Discord
      description: 'Voice, video and text communication'
      category: 'Communication'
      
      linux:
        install_method: 'flatpak'
        install_command: 'flatpak install flathub com.discordapp.Discord'
        
      macos:
        install_method: 'brew'
        install_command: '--cask discord'
        
      windows:
        install_method: 'winget'
        install_command: 'Discord.Discord'

Development Environment

desktop_applications:
  development:
    - name: GitKraken
      description: 'Git GUI client'
      category: 'Development'
      
      linux:
        install_method: 'snap'
        install_command: 'gitkraken --classic'
        
      macos:
        install_method: 'brew'
        install_command: '--cask gitkraken'
        
      windows:
        install_method: 'winget'
        install_command: 'Axosoft.GitKraken'
        
    - name: Postman
      description: 'API development environment'
      category: 'Development'
      
      linux:
        install_method: 'snap'
        install_command: 'postman'
        
      macos:
        install_method: 'brew'
        install_command: '--cask postman'
        
      windows:
        install_method: 'winget'
        install_command: 'Postman.Postman'

    - name: DBeaver
      description: 'Universal database tool'
      category: 'Development'
      
      linux:
        install_method: 'flatpak'
        install_command: 'flatpak install flathub io.dbeaver.DBeaverCommunity'
        
      macos:
        install_method: 'brew'
        install_command: '--cask dbeaver-community'
        
      windows:
        install_method: 'winget'
        install_command: 'dbeaver.dbeaver'

GNOME Customization Profile

# Complete GNOME setup for development
platforms: ["linux"]

themes:
  - name: 'Development Theme'
    theme_color: 'blue'
    theme_background: 'assets/themes/dev/background.jpg'
    neovim_colorscheme: 'assets/themes/dev/neovim.lua'

settings:
  # Window management for development
  - name: 'Developer Tweaks'
    settings:
      - key: 'org.gnome.mutter center-new-windows'
        value: true
      - key: 'org.gnome.desktop.interface monospace-font-name'
        value: 'JetBrainsMono Nerd Font 11'
      - key: 'org.gnome.desktop.interface enable-hot-corners'
        value: false
        
  # Development keybindings
  - name: 'Dev Keybindings'
    settings:
      - key: 'org.gnome.desktop.wm.keybindings close'
        value: "['<Super>w']"
      - key: 'org.gnome.desktop.wm.keybindings toggle-fullscreen'
        value: "['<Super>f']"

extensions:
  - id: 'tactile@lundal.io'  # Window tiling
  - id: 'space-bar@luchrioh'  # Workspace names
  - id: 'blur-my-shell@aunetx'  # Visual effects

dock:
  - name: 'VS Code'
    desktop_file: 'code.desktop'
  - name: 'Terminal'
    desktop_file: 'org.gnome.Terminal.desktop'
  - name: 'Firefox'
    desktop_file: 'firefox.desktop'
  - name: 'File Manager'
    desktop_file: 'org.gnome.Nautilus.desktop'

KDE Plasma Configuration

# kde.yaml configuration structure
platforms: ["linux"]

themes:
  - name: 'Breeze Dark'
    plasma_theme: 'breeze-dark'
    color_scheme: 'BreezeDark'
    
settings:
  - name: 'Window Behavior'
    config_file: '~/.config/kwinrc'
    settings:
      - group: 'Windows'
        key: 'FocusPolicy'
        value: 'FocusFollowsMouse'
        
  - name: 'Shortcuts'
    config_file: '~/.config/kglobalshortcutsrc'
    settings:
      - group: 'kwin'
        key: 'Window Close'
        value: 'Meta+W'

plasmoids:
  - name: 'System Monitor'
    package: 'org.kde.plasma.systemmonitor'
    location: 'panel'
    
widgets:
  - name: 'Task Manager'
    type: 'org.kde.plasma.taskmanager'
    settings:
      groupingStrategy: 0  # Do not group

macOS Configuration

# macos.yaml configuration structure  
platforms: ["macos"]

system_preferences:
  - domain: 'com.apple.dock'
    settings:
      - key: 'autohide'
        type: 'bool'
        value: true
      - key: 'tilesize'
        type: 'int'
        value: 48
        
  - domain: 'NSGlobalDomain'
    settings:
      - key: 'AppleKeyboardUIMode'
        type: 'int'
        value: 3  # Full keyboard access
        
dock_items:
  - name: 'Finder'
    path: '/System/Applications/Finder.app'
  - name: 'VS Code'
    path: '/Applications/Visual Studio Code.app'
  - name: 'Terminal'
    path: '/Applications/Utilities/Terminal.app'

Validation and Testing

Configuration Validation

# Validate desktop configuration
devex config validate desktop

# Test application installation (dry-run)
devex install --category productivity --dry-run

# Validate GNOME settings
devex desktop apply --dry-run

# Check installed desktop applications
devex list --desktop-only

GNOME Validation

# Test GNOME settings application
gsettings list-schemas | grep tactile

# Verify extension installation
gnome-extensions list --enabled

# Check dconf settings
dconf dump /org/gnome/shell/extensions/

Troubleshooting

# Flatpak issues
flatpak repair
flatpak update

# Snap issues
sudo snap refresh

# Check desktop file
ls /usr/share/applications/ | grep app-name

# Regenerate desktop database
update-desktop-database ~/.local/share/applications/

Best Practices

Desktop Configuration Best Practices:

Use official package sources - Prefer Flatpak/Snap for Linux apps
Test extensions carefully - GNOME extensions can be fragile
Backup settings - Export dconf/registry before major changes
Version pin themes - Avoid theme breaking changes
Document customizations - Share team desktop configurations
Test across DEs - Ensure apps work on different desktop environments

Applications Configuration - Command-line applications
System Configuration - System-level settings
Platform Support - Platform-specific details
CLI Reference: Desktop - Desktop management commands

Desktop configuration provides a complete GUI environment setup, from application installation to desktop environment customization. It ensures consistent visual and functional experiences across development machines.

Desktop Configuration

Desktop ConfigurationCopy Anchor Link

File LocationCopy Anchor Link

File StructureCopy Anchor Link

Desktop ApplicationsCopy Anchor Link

Application SchemaCopy Anchor Link

Platform-Specific ConfigurationCopy Anchor Link

Application CategoriesCopy Anchor Link

Productivity

Development

Multimedia

Communication

Desktop Environment Specific ConfigurationCopy Anchor Link

GNOME ConfigurationCopy Anchor Link

GNOME Settings ConfigurationCopy Anchor Link

Theme ManagementCopy Anchor Link

Real-World Configuration ExamplesCopy Anchor Link

Productivity-Focused SetupCopy Anchor Link

Development EnvironmentCopy Anchor Link

GNOME Customization ProfileCopy Anchor Link

KDE Plasma ConfigurationCopy Anchor Link

macOS ConfigurationCopy Anchor Link

Validation and TestingCopy Anchor Link

Configuration ValidationCopy Anchor Link

GNOME ValidationCopy Anchor Link

TroubleshootingCopy Anchor Link

Best PracticesCopy Anchor Link

Related DocumentationCopy Anchor Link

On this page

Desktop Configuration

File Location

File Structure

Desktop Applications

Application Schema

Platform-Specific Configuration

Application Categories

Desktop Environment Specific Configuration

GNOME Configuration

GNOME Settings Configuration

Theme Management

Real-World Configuration Examples

Productivity-Focused Setup

Development Environment

GNOME Customization Profile

KDE Plasma Configuration

macOS Configuration

Validation and Testing

Configuration Validation

GNOME Validation

Troubleshooting

Best Practices

Related Documentation