Add device architecture documentation and D2 diagram
Some checks failed
Flake checker / Build Nix targets (push) Has been cancelled
Some checks failed
Flake checker / Build Nix targets (push) Has been cancelled
- Add comprehensive DEVICE_ARCHITECTURE.md with detailed device specifications - Create D2 diagram showing device relationships and network topology - Organize assets in dedicated assets/ folder - Document all devices: servers (mirai, deoxys, tsuba), workstations (ryu), and portable devices (kuro, shiro, SteamDeck) - Include deployment flows, network architecture, and build infrastructure
This commit is contained in:
uttarayan21
211
DEVICE_ARCHITECTURE.md
Normal file
211
DEVICE_ARCHITECTURE.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# Device Architecture Overview
|
||||
|
||||
This document provides a comprehensive overview of all devices managed by this NixOS/nix-darwin dotfiles repository.
|
||||
|
||||
> **Visual Diagram**: See [assets/devices-diagram.svg](assets/devices-diagram.svg) for a visual representation of this architecture.
|
||||
|
||||
## Device Categories
|
||||
|
||||
### 🖥️ Server Infrastructure (Headless)
|
||||
|
||||
#### mirai (Main Server)
|
||||
- **Architecture**: x86_64-linux
|
||||
- **User**: fs0c131y
|
||||
- **Role**: Primary server hosting various services
|
||||
- **Configuration**: NixOS + Home Manager
|
||||
- **Hardware**: AMD CPU with NVME storage
|
||||
- **Location**: Local network
|
||||
- **Services**:
|
||||
- Nextcloud (file storage and sync)
|
||||
- Gitea (Git hosting)
|
||||
- Grafana (monitoring and dashboards)
|
||||
- Minecraft server
|
||||
- Immich (photo management)
|
||||
- Paperless (document management)
|
||||
- Tailscale VPN node
|
||||
- ZeroTier network node
|
||||
- Atuin (shell history sync)
|
||||
- LLDAP (LDAP server)
|
||||
- Navidrome (music streaming)
|
||||
- Searxng (search engine)
|
||||
- Syncthing
|
||||
- And many more services
|
||||
|
||||
#### deoxys (VM Server)
|
||||
- **Architecture**: x86_64-linux
|
||||
- **User**: servius
|
||||
- **Role**: Virtual machine server for testing and isolation
|
||||
- **Configuration**: NixOS + Home Manager
|
||||
- **Location**: Local network
|
||||
|
||||
#### tsuba (Raspberry Pi)
|
||||
- **Architecture**: aarch64-linux
|
||||
- **User**: servius
|
||||
- **Role**: ARM-based server for lightweight services
|
||||
- **Configuration**: NixOS + Home Manager (using stable channel)
|
||||
- **Hardware**: Raspberry Pi
|
||||
- **Access**: External via tsuba.darksailor.dev
|
||||
- **Special**: Uses nixos-raspberrypi input for hardware support
|
||||
|
||||
### 💻 Development Workstations
|
||||
|
||||
#### ryu (Main Desktop)
|
||||
- **Architecture**: x86_64-linux
|
||||
- **User**: servius
|
||||
- **Role**: Primary development workstation
|
||||
- **Configuration**: NixOS + Home Manager
|
||||
- **Desktop Environment**: Hyprland (primary) + GNOME (fallback)
|
||||
- **Features**:
|
||||
- Multi-monitor setup:
|
||||
- Primary: HDMI-A-1 (Gigabyte FO27Q3)
|
||||
- Secondary: DP-3 (Acer XV272U)
|
||||
- Tertiary: DP-1 (Gigabyte M27Q)
|
||||
- Audio production setup (musnix)
|
||||
- Gaming support (Wine, Steam)
|
||||
- Virtualization (virt-manager)
|
||||
- Hardware acceleration (CUDA support)
|
||||
- Secure boot with Lanzaboote
|
||||
- TPM2 support
|
||||
|
||||
### 📱 Portable/Mobile Devices
|
||||
|
||||
#### kuro (MacBook)
|
||||
- **Architecture**: aarch64-darwin (Apple Silicon)
|
||||
- **User**: fs0c131y
|
||||
- **Role**: macOS development machine
|
||||
- **Configuration**: nix-darwin + Home Manager
|
||||
- **Features**:
|
||||
- Touch ID for sudo authentication
|
||||
- Custom keyboard mappings
|
||||
- Homebrew integration
|
||||
|
||||
#### shiro (MacBook)
|
||||
- **Architecture**: aarch64-darwin (Apple Silicon)
|
||||
- **User**: servius
|
||||
- **Role**: Secondary macOS machine
|
||||
- **Configuration**: nix-darwin + Home Manager
|
||||
|
||||
#### SteamDeck (Gaming Handheld)
|
||||
- **Architecture**: x86_64-linux
|
||||
- **User**: deck
|
||||
- **Role**: Portable gaming device
|
||||
- **Configuration**: Home Manager only (no NixOS)
|
||||
- **Special**: Uses SteamOS with Home Manager overlay
|
||||
|
||||
## Network Architecture
|
||||
|
||||
### VPN Networks
|
||||
- **Tailscale**: Primary VPN connecting most devices
|
||||
- Devices: mirai, deoxys, tsuba, deck
|
||||
- **ZeroTier**: Secondary network layer
|
||||
- Devices: mirai, ryu
|
||||
|
||||
### Local Network
|
||||
- **Primary connection**: ryu (main desktop)
|
||||
- **Wake-on-LAN**: Enabled for ryu (eno1 interface)
|
||||
|
||||
## Configuration Management
|
||||
|
||||
### NixOS Flake
|
||||
- **Manages**: mirai, deoxys, tsuba, ryu
|
||||
- **Features**: Unified configuration across Linux devices
|
||||
- **Inputs**: Multiple flake inputs for extended functionality
|
||||
|
||||
### nix-darwin
|
||||
- **Manages**: kuro, shiro
|
||||
- **Features**: macOS system configuration
|
||||
|
||||
### Home Manager
|
||||
- **Standalone**: deck (SteamDeck)
|
||||
- **Integrated**: All other devices
|
||||
- **Stable channel**: Used for tsuba
|
||||
|
||||
## Build Infrastructure
|
||||
|
||||
### Distributed Building
|
||||
- **Build machines**:
|
||||
- mirai (primary build server)
|
||||
- shiro (macOS builds)
|
||||
- tsuba (ARM builds, commented out)
|
||||
- **Consumers**:
|
||||
- ryu (uses remote builders)
|
||||
- kuro (uses remote builders)
|
||||
|
||||
### Cache Strategy
|
||||
- **Substituters**:
|
||||
- nix-community.cachix.org
|
||||
- nixos-raspberrypi.cachix.org (for ARM builds)
|
||||
- **Build optimization**: Auto-optimise-store enabled
|
||||
|
||||
## Deployment Strategy
|
||||
|
||||
### SSH-based Deployment
|
||||
Using deploy-rs for automated deployments:
|
||||
|
||||
```
|
||||
ryu → mirai, deoxys, tsuba, deck
|
||||
kuro → mirai, shiro
|
||||
```
|
||||
|
||||
### Special Access
|
||||
- **tsuba**: Accessed via external domain (tsuba.darksailor.dev)
|
||||
- **All servers**: SSH key authentication with authorized_keys
|
||||
|
||||
## Hardware-Specific Features
|
||||
|
||||
### ryu (Desktop)
|
||||
- **Graphics**: NVIDIA with CUDA support
|
||||
- **Audio**: Professional audio setup with musnix
|
||||
- **Input devices**: QMK keyboard support
|
||||
- **Monitors**: DDC/CI control with ddcutil
|
||||
- **Security**: TPM2, secure boot (Lanzaboote)
|
||||
|
||||
### mirai (Server)
|
||||
- **CPU**: AMD with virtualization support
|
||||
- **Storage**: Custom disk layout with disko
|
||||
- **Containers**: Docker with custom mount points
|
||||
- **Emulation**: aarch64-linux binfmt support
|
||||
|
||||
### macOS Devices (kuro, shiro)
|
||||
- **Authentication**: Touch ID integration
|
||||
- **Keyboard**: Custom modifier key mappings
|
||||
- **Package management**: Homebrew + Nix hybrid approach
|
||||
|
||||
## Security Features
|
||||
|
||||
- **SOPS**: Secrets management across all devices
|
||||
- **SSH keys**: Centralized key management
|
||||
- **Fail2ban**: Enabled on mirai
|
||||
- **Secure boot**: Implemented on ryu
|
||||
- **TPM**: Hardware security on ryu
|
||||
|
||||
## Development Environment
|
||||
|
||||
### Shared Tools
|
||||
- **Editor**: Nixvim (custom Neovim configuration)
|
||||
- **Shell**: Fish + Nushell support
|
||||
- **Terminal**: Various per-device preferences
|
||||
- **Version control**: Git with shared configuration
|
||||
|
||||
### Language Support
|
||||
- **Rust**: Custom overlay with latest toolchain
|
||||
- **Python**: Python 3 with development tools
|
||||
- **Nix**: Latest Nix with flakes enabled
|
||||
- **Web**: Node.js and web development tools
|
||||
|
||||
## Monitoring and Observability
|
||||
|
||||
- **Grafana**: Centralized monitoring on mirai
|
||||
- **System metrics**: Collected across all NixOS devices
|
||||
- **Shell history**: Synchronized via Atuin
|
||||
- **File synchronization**: Syncthing for selective sync
|
||||
|
||||
## Backup and Data Management
|
||||
|
||||
- **Nextcloud**: Primary cloud storage on mirai
|
||||
- **Syncthing**: Decentralized file sync
|
||||
- **Git repositories**: Self-hosted on Gitea (mirai)
|
||||
- **Photos**: Immich for photo management
|
||||
- **Documents**: Paperless for document archival
|
||||
|
||||
This architecture provides a robust, scalable, and maintainable infrastructure for development, gaming, media consumption, and server hosting across multiple platforms and architectures.
|
||||
235
assets/devices-diagram.d2
Normal file
235
assets/devices-diagram.d2
Normal file
@@ -0,0 +1,235 @@
|
||||
title: Device Architecture Overview {
|
||||
near: top-center
|
||||
shape: text
|
||||
style: {
|
||||
font-size: 24
|
||||
bold: true
|
||||
}
|
||||
}
|
||||
|
||||
# Device Groups
|
||||
servers: Server Infrastructure {
|
||||
style.fill: "#e8f4fd"
|
||||
style.stroke: "#1e3a8a"
|
||||
style.stroke-width: 2
|
||||
|
||||
mirai: mirai {
|
||||
shape: rectangle
|
||||
style.fill: "#fbbf24"
|
||||
|
||||
label: "mirai\nMain Server\nx86_64-linux\nUser: fs0c131y\nHeadless"
|
||||
|
||||
services: Services {
|
||||
shape: cylinder
|
||||
style.fill: "#34d399"
|
||||
label: "Services\n• Nextcloud\n• Gitea\n• Grafana\n• Minecraft\n• Immich\n• Paperless\n• Tailscale\n• And more..."
|
||||
}
|
||||
}
|
||||
|
||||
deoxys: deoxys {
|
||||
shape: rectangle
|
||||
style.fill: "#a78bfa"
|
||||
label: "deoxys\nVM Server\nx86_64-linux\nUser: servius\nHeadless"
|
||||
}
|
||||
|
||||
tsuba: tsuba {
|
||||
shape: rectangle
|
||||
style.fill: "#fb7185"
|
||||
label: "tsuba\nRaspberry Pi\naarch64-linux\nUser: servius\nHeadless"
|
||||
}
|
||||
}
|
||||
|
||||
workstations: Development Workstations {
|
||||
style.fill: "#f0fdf4"
|
||||
style.stroke: "#15803d"
|
||||
style.stroke-width: 2
|
||||
|
||||
ryu: ryu {
|
||||
shape: rectangle
|
||||
style.fill: "#3b82f6"
|
||||
label: "ryu\nMain Desktop\nx86_64-linux\nUser: servius\nHyprland + GNOME"
|
||||
|
||||
monitors: Multi-Monitor Setup {
|
||||
style.fill: "#ddd6fe"
|
||||
|
||||
primary: "HDMI-A-1\n(Gigabyte FO27Q3)" {
|
||||
shape: rectangle
|
||||
style.fill: "#c4b5fd"
|
||||
}
|
||||
secondary: "DP-3\n(Acer XV272U)" {
|
||||
shape: rectangle
|
||||
style.fill: "#c4b5fd"
|
||||
}
|
||||
tertiary: "DP-1\n(Gigabyte M27Q)" {
|
||||
shape: rectangle
|
||||
style.fill: "#c4b5fd"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
mobile: Portable Devices {
|
||||
style.fill: "#fef3c7"
|
||||
style.stroke: "#d97706"
|
||||
style.stroke-width: 2
|
||||
|
||||
kuro: kuro {
|
||||
shape: rectangle
|
||||
style.fill: "#6b7280"
|
||||
label: "kuro\nMacBook\naarch64-darwin\nUser: fs0c131y"
|
||||
}
|
||||
|
||||
shiro: shiro {
|
||||
shape: rectangle
|
||||
style.fill: "#9ca3af"
|
||||
label: "shiro\nMacBook\naarch64-darwin\nUser: servius"
|
||||
}
|
||||
|
||||
deck: SteamDeck {
|
||||
shape: rectangle
|
||||
style.fill: "#ef4444"
|
||||
label: "SteamDeck\nGaming Handheld\nx86_64-linux\nUser: deck\nHome Manager Only"
|
||||
}
|
||||
}
|
||||
|
||||
# Network Infrastructure
|
||||
network: Network Infrastructure {
|
||||
style.fill: "#fdf2f8"
|
||||
style.stroke: "#db2777"
|
||||
style.stroke-width: 2
|
||||
|
||||
tailscale: Tailscale VPN {
|
||||
shape: cloud
|
||||
style.fill: "#ec4899"
|
||||
}
|
||||
|
||||
zerotier: ZeroTier Network {
|
||||
shape: cloud
|
||||
style.fill: "#f97316"
|
||||
}
|
||||
|
||||
local_network: Local Network {
|
||||
shape: cloud
|
||||
style.fill: "#06b6d4"
|
||||
}
|
||||
}
|
||||
|
||||
# Build Infrastructure
|
||||
builders: Build Machines {
|
||||
style.fill: "#f5f5f4"
|
||||
style.stroke: "#525252"
|
||||
style.stroke-width: 2
|
||||
|
||||
build_info: "Distributed Builds\nmirai, shiro (+ tsuba)" {
|
||||
shape: text
|
||||
style.font-size: 14
|
||||
style.bold: true
|
||||
}
|
||||
}
|
||||
|
||||
# Configuration Management
|
||||
config_mgmt: Configuration Management {
|
||||
style.fill: "#fefce8"
|
||||
style.stroke: "#ca8a04"
|
||||
style.stroke-width: 2
|
||||
|
||||
nixos_flake: NixOS Flake {
|
||||
shape: hexagon
|
||||
style.fill: "#facc15"
|
||||
}
|
||||
|
||||
home_manager: Home Manager {
|
||||
shape: hexagon
|
||||
style.fill: "#eab308"
|
||||
}
|
||||
|
||||
darwin: nix-darwin {
|
||||
shape: hexagon
|
||||
style.fill: "#f59e0b"
|
||||
}
|
||||
}
|
||||
|
||||
# Deployment Connections
|
||||
workstations.ryu -> servers.mirai: SSH Deploy {
|
||||
style.stroke: "#059669"
|
||||
style.stroke-width: 2
|
||||
}
|
||||
|
||||
workstations.ryu -> servers.deoxys: SSH Deploy {
|
||||
style.stroke: "#059669"
|
||||
style.stroke-width: 2
|
||||
}
|
||||
|
||||
workstations.ryu -> servers.tsuba: "SSH Deploy\n(tsuba.darksailor.dev)" {
|
||||
style.stroke: "#059669"
|
||||
style.stroke-width: 2
|
||||
}
|
||||
|
||||
mobile.kuro -> servers.mirai: SSH Deploy {
|
||||
style.stroke: "#7c3aed"
|
||||
style.stroke-width: 2
|
||||
}
|
||||
|
||||
mobile.kuro -> mobile.shiro: SSH Deploy {
|
||||
style.stroke: "#7c3aed"
|
||||
style.stroke-width: 2
|
||||
}
|
||||
|
||||
workstations.ryu -> mobile.deck: "SSH Deploy\n(steamdeck)" {
|
||||
style.stroke: "#dc2626"
|
||||
style.stroke-width: 2
|
||||
}
|
||||
|
||||
# Network connections
|
||||
servers.mirai -> network.tailscale
|
||||
servers.deoxys -> network.tailscale
|
||||
servers.tsuba -> network.tailscale
|
||||
workstations.ryu -> network.local_network
|
||||
mobile.deck -> network.tailscale
|
||||
|
||||
servers.mirai -> network.zerotier
|
||||
workstations.ryu -> network.zerotier
|
||||
|
||||
# Build relationships
|
||||
workstations.ryu -> builders: Uses distributed builds
|
||||
mobile.kuro -> builders: Uses distributed builds
|
||||
servers.mirai -> builders: Build server
|
||||
mobile.shiro -> builders: Build server
|
||||
|
||||
# Configuration connections
|
||||
config_mgmt.nixos_flake -> servers.mirai
|
||||
config_mgmt.nixos_flake -> servers.deoxys
|
||||
config_mgmt.nixos_flake -> servers.tsuba
|
||||
config_mgmt.nixos_flake -> workstations.ryu
|
||||
|
||||
config_mgmt.darwin -> mobile.kuro
|
||||
config_mgmt.darwin -> mobile.shiro
|
||||
|
||||
config_mgmt.home_manager -> mobile.deck
|
||||
|
||||
# Legend
|
||||
legend: Legend {
|
||||
near: bottom-right
|
||||
style.fill: "#f9fafb"
|
||||
style.stroke: "#6b7280"
|
||||
|
||||
servers_legend: "🖥️ Servers (headless)" {
|
||||
shape: text
|
||||
style.font-size: 12
|
||||
}
|
||||
|
||||
workstations_legend: "💻 Workstations (GUI)" {
|
||||
shape: text
|
||||
style.font-size: 12
|
||||
}
|
||||
|
||||
mobile_legend: "📱 Portable/Mobile" {
|
||||
shape: text
|
||||
style.font-size: 12
|
||||
}
|
||||
|
||||
deploy_legend: "→ SSH Deploy" {
|
||||
shape: text
|
||||
style.font-size: 12
|
||||
}
|
||||
}
|
||||
149
assets/devices-diagram.svg
Normal file
149
assets/devices-diagram.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 64 KiB |
Reference in New Issue
Block a user