Add Steam Deck (nix-deck) configuration with Jovian-NixOS and remote building
- Add Jovian-NixOS integration for Steam Deck hardware support - Create nix-deck machine configuration with SteamOS role - Add jovian-compat.nix for NixOS 25.05 compatibility (remove in 25.11+) - Create remote-build role for distributed builds - Configure zix790prors as build host - Configure nix-book and nix-deck to use remote builder with fallback - Add comprehensive setup documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
280
STEAM_DECK_JOVIAN_SETUP.md
Normal file
280
STEAM_DECK_JOVIAN_SETUP.md
Normal file
@@ -0,0 +1,280 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user