Remove transition documentation
This commit is contained in:
@@ -1,280 +0,0 @@
|
|||||||
# 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