nixos-configs/STEAM_DECK_JOVIAN_SETUP.md

# Steam Deck (nix-deck) Jovian-NixOS Setup Guide

This document describes the setup for installing and maintaining NixOS with Jovian-NixOS on a Steam Deck.

## Overview

The `nix-deck` configuration provides:
- **Jovian-NixOS integration** for Steam Deck hardware support
- **Remote building** using `zix790prors` as the build host
- **SteamOS role** for easy Steam Deck UI configuration
- **Compatibility shim** for using Jovian on NixOS 25.05 stable

## Architecture

### Remote Building

The setup uses distributed builds to avoid slow compilation on the Steam Deck:

- **Build Host**: `zix790prors` (powerful desktop)
  - Runs as a dedicated `nix-builder` user (not root)
  - Accepts SSH connections from client machines
  - Performs all heavy compilation work

- **Build Clients**: `nix-book` and `nix-deck`
  - Automatically offload builds to `zix790prors`
  - Fall back to local building if remote builder is unavailable
  - Steam Deck heavily prefers remote (speedFactor=4)

### Jovian-NixOS Integration

- **Jovian module**: Provides Steam Deck hardware support, drivers, and Steam UI
- **Compatibility layer**: `roles/jovian-compat.nix` provides `services.logind.settings` for NixOS 25.05
  - **IMPORTANT**: Remove this when upgrading to NixOS 25.11+
  - An assertion will fail the build if used on 25.11+

- **SteamOS role**: `roles.desktop.steamos` abstracts Jovian configuration
  ```nix
  roles.desktop.steamos = {
    enable = true;
    autoStart = false;  # Set to true to boot directly to Steam UI
    desktopSession = "plasmawayland";
  };
  ```

## Initial Installation

### Prerequisites

1. Steam Deck in recovery mode or booted to a live Linux environment
2. SSH access enabled on the Steam Deck
3. SSH key set up for passwordless authentication

### Option 1: Using nixos-anywhere (Initial Install Only)

```bash
# From your main machine
nix run github:nix-community/nixos-anywhere -- \
  --flake .#nix-deck \
  root@<steam-deck-ip>
```

**Note**: This is only for the initial install. For updates, see below.

### Option 2: Manual Installation

1. Boot Steam Deck from NixOS installer USB
2. Partition and format the disk
3. Mount filesystems
4. Clone this repository
5. Generate hardware config:
   ```bash
   nixos-generate-config --show-hardware-config > /tmp/hw.nix
   ```
6. Copy the hardware config content to `machines/nix-deck/hardware-configuration.nix`
7. Keep the `jovian.devices.steamdeck` settings in the file
8. Install:
   ```bash
   nixos-install --flake .#nix-deck
   ```

## Updates and Rebuilds

### Method 1: Remote Build and Deploy (Recommended)

Build on your main machine, deploy to Steam Deck:

```bash
# From nix-book or zix790prors
nixos-rebuild switch \
  --flake .#nix-deck \
  --target-host root@nix-deck \
  --build-host localhost
```

### Method 2: On-Device Rebuild (Uses Remote Builder)

The Steam Deck is configured to automatically use `zix790prors` as a remote builder:

```bash
# SSH into the Steam Deck
ssh root@nix-deck

# This will automatically build on zix790prors
nixos-rebuild switch --flake /path/to/nixos-configs#nix-deck
```

The build will automatically happen on `zix790prors` and be deployed locally.

## Remote Builder Setup

### On the Build Host (zix790prors)

The configuration creates a `nix-builder` user that client machines connect to:

```nix
roles.remote-build.enableBuilder = true;
```

### On Client Machines (nix-book, nix-deck)

Configure the remote builder:

```nix
roles.remote-build.builders = [{
  hostName = "zix790prors";
  maxJobs = 16;
  speedFactor = 4;  # Higher = prefer remote more
}];
```

### SSH Key Setup

1. Generate SSH key on the builder host for the `nix-builder` user:
   ```bash
   sudo -u nix-builder ssh-keygen -t ed25519 -f /var/lib/nix-builder/.ssh/id_ed25519
   ```

2. Copy the public key to client machines:
   ```bash
   # Add to /var/lib/nix-builder/.ssh/authorized_keys on zix790prors
   ```

3. On client machines, ensure you can connect:
   ```bash
   ssh nix-builder@zix790prors
   ```

## Configuration Files

### Key Files Created/Modified

- `flake.nix` - Added Jovian input and nix-deck configuration
- `roles/jovian-compat.nix` - Compatibility shim (remove in 25.11+)
- `roles/desktop/steamos.nix` - SteamOS/Jovian role abstraction
- `roles/remote-build/default.nix` - Remote builder role
- `machines/nix-deck/configuration.nix` - Steam Deck system config
- `machines/nix-deck/hardware-configuration.nix` - Hardware config (placeholder)

### Example Configuration

```nix
# machines/nix-deck/configuration.nix
{
  roles = {
    desktop = {
      enable = true;
      wayland = true;
      gaming.enable = true;
      kde = true;
      sddm = true;
      steamos = {
        enable = true;
        autoStart = false;  # or true to boot to Steam UI
        desktopSession = "plasmawayland";
      };
    };
    remote-build.builders = [{
      hostName = "zix790prors";
      maxJobs = 16;
      speedFactor = 4;
    }];
  };
}
```

## Jovian Features

### Enabled by Default

- Steam Deck hardware support (`jovian.devices.steamdeck.enable`)
- Steam UI (`jovian.steam.enable`)
- Decky Loader plugin system (`jovian.decky-loader.enable`)

### Optional Features

Set in the hardware-configuration.nix:

```nix
jovian.devices.steamdeck = {
  enable = true;
  autoUpdate = false;  # Auto-update BIOS/controller firmware
};
```

### Manual Firmware Updates

```bash
# BIOS update
sudo jupiter-biosupdate

# Controller update
sudo jupiter-controller-update

# Docking station (connect via USB-C first)
jupiter-dock-updater
```

## Troubleshooting

### Remote Builds Not Working

1. Check SSH connectivity:
   ```bash
   ssh nix-builder@zix790prors
   ```

2. Verify builder is trusted:
   ```bash
   # On zix790prors
   nix show-config | grep trusted-users
   ```

3. Check build logs:
   ```bash
   journalctl -u nix-daemon -f
   ```

### Jovian Not Working

1. Ensure you're on NixOS 25.05 or the compatibility layer is removed for 25.11+
2. Check Jovian is imported in flake.nix
3. Verify hardware config has `jovian.devices.steamdeck.enable = true`

### Compatibility Layer Issues

If you see an error about `jovian-compat.nix` being incompatible:

1. You're running NixOS 25.11 or later
2. Remove `./roles/jovian-compat.nix` from `flake.nix`
3. Jovian should work natively on 25.11+

## Future Upgrades

### Upgrading to NixOS 25.11

1. Update `nixpkgs` input in flake.nix to 25.11
2. Remove `./roles/jovian-compat.nix` from flake.nix imports
3. The assertion in jovian-compat.nix will prevent accidental use
4. Test the build
5. Deploy

### Switching to Unstable

If you need Jovian to follow unstable nixpkgs:

1. Edit `flake.nix`:
   ```nix
   jovian = {
     url = "github:Jovian-Experiments/Jovian-NixOS";
     inputs.nixpkgs.follows = "nixpkgs-unstable";
   };
   ```

2. This only affects Jovian packages, not your base system

## Additional Resources

- [Jovian-NixOS Documentation](https://jovian-experiments.github.io/Jovian-NixOS/)
- [Jovian Steam Deck Guide](https://jovian-experiments.github.io/Jovian-NixOS/devices/valve-steam-deck/)
- [NixOS Remote Builds](https://nixos.org/manual/nix/stable/advanced-topics/distributed-builds.html)