# DKMS and NVIDIA User Guide for Particle-OS

## Overview

Particle-OS includes comprehensive DKMS (Dynamic Kernel Module Support) and NVIDIA driver support, enabling users to install proprietary drivers and kernel modules while maintaining the immutable system architecture. This guide covers common use cases and best practices.

## Quick Start

### Installing NVIDIA Drivers

```bash
# Auto-detect and install optimal NVIDIA driver
sudo apt-layer --nvidia-install auto

# Install specific driver version
sudo apt-layer --nvidia-install 535

# Check NVIDIA driver status
sudo apt-layer --nvidia-status
```

### Installing DKMS Modules

```bash
# Install VirtualBox DKMS module
sudo apt-layer --dkms-install virtualbox-dkms 6.1.38

# Install VMware DKMS module
sudo apt-layer --dkms-install open-vm-tools-dkms 12.3.0

# Check DKMS status
sudo apt-layer --dkms-status
```

## Common Use Cases

### Gaming Setup with NVIDIA

```bash
# 1. Install NVIDIA drivers
sudo apt-layer --nvidia-install auto

# 2. Configure NVIDIA Prime for GPU switching
sudo apt-layer --nvidia-prime-configure

# 3. Switch to NVIDIA GPU for gaming
sudo apt-layer --gpu-switch nvidia

# 4. Install gaming software
sudo apt-layer install steam wine lutris

# 5. Verify NVIDIA drivers are working
sudo apt-layer --nvidia-status
```

### Virtualization Setup

```bash
# 1. Install VirtualBox DKMS module
sudo apt-layer --dkms-install virtualbox-dkms 6.1.38

# 2. Install VirtualBox
sudo apt-layer install virtualbox

# 3. Verify DKMS module is installed
sudo apt-layer --dkms-status

# 4. Start VirtualBox
virtualbox
```

### VMware Workstation Setup

```bash
# 1. Install VMware DKMS module
sudo apt-layer --dkms-install open-vm-tools-dkms 12.3.0

# 2. Install VMware Workstation
sudo apt-layer install vmware-workstation

# 3. Rebuild DKMS modules if needed
sudo apt-layer --dkms-rebuild-all

# 4. Start VMware Workstation
vmware
```

## Advanced DKMS Management

### Kernel Updates and DKMS

When the kernel is updated, DKMS modules need to be rebuilt:

```bash
# 1. Update system (includes kernel updates)
sudo apt-layer upgrade

# 2. Rebuild all DKMS modules for new kernel
sudo apt-layer --dkms-rebuild-all

# 3. Verify all modules are rebuilt
sudo apt-layer --dkms-status
```

### Specific Module Management

```bash
# Rebuild specific module
sudo apt-layer --dkms-rebuild virtualbox-dkms 6.1.38

# Remove specific module
sudo apt-layer --dkms-remove virtualbox-dkms 6.1.38

# List all installed modules
sudo apt-layer --dkms-list
```

### NVIDIA GPU Switching

```bash
# Switch to NVIDIA GPU (performance mode)
sudo apt-layer --gpu-switch nvidia

# Switch to integrated GPU (power saving mode)
sudo apt-layer --gpu-switch integrated

# Use automatic GPU switching
sudo apt-layer --gpu-switch auto

# Check current GPU status
sudo apt-layer --nvidia-status
```

## Troubleshooting

### DKMS Build Failures

If DKMS module installation fails:

```bash
# 1. Check DKMS status for errors
sudo apt-layer --dkms-status

# 2. Install kernel headers if missing
sudo apt-layer install linux-headers-$(uname -r)

# 3. Try rebuilding the module
sudo apt-layer --dkms-rebuild-all

# 4. Check system logs for detailed errors
sudo journalctl -xe
```

### NVIDIA Driver Issues

If NVIDIA drivers aren't working:

```bash
# 1. Check NVIDIA driver status
sudo apt-layer --nvidia-status

# 2. Reinstall NVIDIA drivers
sudo apt-layer --nvidia-install auto

# 3. Configure NVIDIA Prime
sudo apt-layer --nvidia-prime-configure

# 4. Switch to NVIDIA GPU
sudo apt-layer --gpu-switch nvidia

# 5. Reboot system
sudo reboot
```

### GPU Switching Issues

If GPU switching isn't working:

```bash
# 1. Check NVIDIA Prime status
sudo apt-layer --nvidia-status

# 2. Reconfigure NVIDIA Prime
sudo apt-layer --nvidia-prime-configure

# 3. Check if prime-select is available
which prime-select

# 4. Manually switch GPU
sudo prime-select nvidia
sudo prime-select intel
sudo prime-select query
```

## Best Practices

### 1. Always Use Atomic Operations

Particle-OS DKMS commands use atomic transactions with automatic rollback:

```bash
# Safe installation with rollback on failure
sudo apt-layer --dkms-install module-name version

# Safe removal with rollback on failure
sudo apt-layer --dkms-remove module-name version
```

### 2. Check Status After Operations

Always verify that operations completed successfully:

```bash
# Check DKMS status after installation
sudo apt-layer --dkms-status

# Check NVIDIA status after driver installation
sudo apt-layer --nvidia-status
```

### 3. Rebuild After Kernel Updates

Always rebuild DKMS modules after kernel updates:

```bash
# After system upgrade
sudo apt-layer upgrade
sudo apt-layer --dkms-rebuild-all
```

### 4. Use Auto-Detection for NVIDIA Drivers

Let Particle-OS auto-detect the optimal NVIDIA driver:

```bash
# Auto-detect is usually the best choice
sudo apt-layer --nvidia-install auto
```

### 5. Configure NVIDIA Prime for Laptops

For laptops with dual GPUs, configure NVIDIA Prime:

```bash
# Configure for automatic GPU switching
sudo apt-layer --nvidia-prime-configure
sudo apt-layer --gpu-switch auto
```

## Gaming Variants

Particle-OS offers pre-configured gaming variants with NVIDIA support:

### Particle-OS Bazzite Gaming (NVIDIA)
- Ubuntu 25.04 base
- Pre-installed NVIDIA drivers
- Gaming optimizations
- Steam, Wine, Lutris integration

### Particle-OS Corona Gaming (NVIDIA)
- Ubuntu 24.04 LTS base
- KDE Plasma desktop
- Pre-installed NVIDIA drivers
- Gaming performance tuning

## Integration with Particle-OS Features

### Atomic Updates with DKMS

DKMS modules are automatically handled during system updates:

```bash
# Update system (includes DKMS module rebuilding)
sudo apt-layer upgrade

# Rollback if DKMS rebuild fails
sudo apt-layer rollback
```

### Live System Operations

DKMS modules can be installed on live systems:

```bash
# Install DKMS module on live system
sudo apt-layer --live-install virtualbox-dkms

# Commit changes as new layer
sudo apt-layer --live-commit "Add VirtualBox DKMS support"
```

### Container-Based Installation

DKMS modules can be installed in isolated containers:

```bash
# Install DKMS module in container
sudo apt-layer --container base-image new-image virtualbox-dkms
```

## Conclusion

Particle-OS provides comprehensive DKMS and NVIDIA support that integrates seamlessly with the immutable system architecture. The atomic operations ensure system stability while providing the flexibility needed for gaming, virtualization, and hardware support.

For more information, see:
- [DKMS and NVIDIA Support Documentation](dkms-nvidia-support.md)
- [DKMS Implementation Plan](dkms-implementation-plan.md)
- [Particle-OS Main Documentation](../README.md)