init by ai
This commit is contained in:
477
CUSTOMIZATION.md
Normal file
477
CUSTOMIZATION.md
Normal file
@@ -0,0 +1,477 @@
|
||||
# Customization Guide
|
||||
|
||||
Advanced customization patterns for your portable NixOS setup.
|
||||
|
||||
## Creating Custom Modules
|
||||
|
||||
### Pattern 1: Language-Specific Development Environment
|
||||
|
||||
Create `nixos/modules/languages/rust.nix`:
|
||||
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
|
||||
{
|
||||
options.custom.languages.rust.enable = lib.mkEnableOption "Rust development";
|
||||
|
||||
config = lib.mkIf config.custom.languages.rust.enable {
|
||||
environment.systemPackages = with pkgs; [
|
||||
rustup
|
||||
cargo-edit
|
||||
cargo-deny
|
||||
rust-analyzer
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Use in `hosts/laptop/default.nix`:
|
||||
```nix
|
||||
custom.languages.rust.enable = true;
|
||||
```
|
||||
|
||||
### Pattern 2: Per-Machine Overrides
|
||||
|
||||
In `nixos/default.nix`:
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
|
||||
{
|
||||
options.custom = {
|
||||
isLaptop = lib.mkOption { type = lib.types.bool; default = false; };
|
||||
isServer = lib.mkOption { type = lib.types.bool; default = false; };
|
||||
};
|
||||
|
||||
config = {
|
||||
# Settings that only apply to laptops
|
||||
power.powertop.enable = lib.mkIf config.custom.isLaptop true;
|
||||
services.thermald.enable = lib.mkIf config.custom.isLaptop true;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
In `hosts/laptop/default.nix`:
|
||||
```nix
|
||||
custom.isLaptop = true;
|
||||
```
|
||||
|
||||
### Pattern 3: Conditional Package Sets
|
||||
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
|
||||
{
|
||||
options.custom.tools.enable = lib.mkEnableOption "Extra tools";
|
||||
|
||||
config = lib.mkIf config.custom.tools.enable {
|
||||
environment.systemPackages = with pkgs; [
|
||||
# Always included
|
||||
git
|
||||
curl
|
||||
|
||||
# Only if GUI is available
|
||||
(lib.optionals (config.custom.hasGui) [
|
||||
firefox
|
||||
vlc
|
||||
])
|
||||
|
||||
# Only on laptops
|
||||
(lib.optionals config.custom.isLaptop [
|
||||
powertop
|
||||
upower
|
||||
])
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Common Customizations
|
||||
|
||||
### Add Docker/Podman Support
|
||||
|
||||
Edit `nixos/modules/development.nix`:
|
||||
|
||||
```nix
|
||||
virtualisation.podman = {
|
||||
enable = true;
|
||||
dockerCompat = true; # Alias docker → podman
|
||||
};
|
||||
|
||||
virtualisation.docker.enable = lib.mkDefault false;
|
||||
```
|
||||
|
||||
### Add Kubernetes Tools
|
||||
|
||||
In `nixos/modules/development.nix`:
|
||||
|
||||
```nix
|
||||
languagePackages = {
|
||||
# ... existing languages
|
||||
kubernetes = with pkgs; [ kubectl helm kustomize ];
|
||||
};
|
||||
```
|
||||
|
||||
Use in host:
|
||||
```nix
|
||||
custom.development.languages = [ "rust" "kubernetes" ];
|
||||
```
|
||||
|
||||
### Add Desktop Environment
|
||||
|
||||
Create `nixos/modules/desktop.nix`:
|
||||
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
|
||||
{
|
||||
options.custom.desktop = {
|
||||
enable = lib.mkEnableOption "Desktop environment";
|
||||
environment = lib.mkOption {
|
||||
type = lib.types.enum [ "gnome" "kde" "xfce" ];
|
||||
default = "gnome";
|
||||
};
|
||||
};
|
||||
|
||||
config = let
|
||||
cfg = config.custom.desktop;
|
||||
in lib.mkIf cfg.enable {
|
||||
services.xserver.enable = true;
|
||||
services.xserver.displayManager.gdm.enable = cfg.environment == "gnome";
|
||||
services.xserver.desktopManager.gnome.enable = cfg.environment == "gnome";
|
||||
|
||||
# Similar for KDE, XFCE...
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Use in host:
|
||||
```nix
|
||||
custom.desktop.enable = true;
|
||||
custom.desktop.environment = "gnome";
|
||||
```
|
||||
|
||||
### Add SSH Server
|
||||
|
||||
Edit `nixos/modules/system.nix`:
|
||||
|
||||
```nix
|
||||
services.openssh = {
|
||||
enable = lib.mkDefault false;
|
||||
ports = [ 22 ];
|
||||
settings = {
|
||||
PermitRootLogin = "no";
|
||||
PasswordAuthentication = false;
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Enable in specific host:
|
||||
```nix
|
||||
# hosts/server/default.nix
|
||||
services.openssh.enable = true;
|
||||
```
|
||||
|
||||
### Add Nginx Web Server
|
||||
|
||||
Create `nixos/modules/web.nix`:
|
||||
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
|
||||
{
|
||||
options.custom.web.enable = lib.mkEnableOption "Web server";
|
||||
|
||||
config = lib.mkIf config.custom.web.enable {
|
||||
services.nginx = {
|
||||
enable = true;
|
||||
virtualHosts."localhost" = {
|
||||
listen = [{ addr = "127.0.0.1"; port = 8080; }];
|
||||
locations."/".root = "/var/www";
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Add PostgreSQL Database
|
||||
|
||||
Create `nixos/modules/database.nix`:
|
||||
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
|
||||
{
|
||||
options.custom.database.postgres.enable = lib.mkEnableOption "PostgreSQL";
|
||||
|
||||
config = lib.mkIf config.custom.database.postgres.enable {
|
||||
services.postgresql = {
|
||||
enable = true;
|
||||
ensureDatabases = [ "dev" ];
|
||||
ensureUsers = [{
|
||||
name = "dev";
|
||||
ensureDBOwnership = true;
|
||||
}];
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Enable in host:
|
||||
```nix
|
||||
custom.database.postgres.enable = true;
|
||||
```
|
||||
|
||||
### Add Docker Containers for Services
|
||||
|
||||
Create `nixos/modules/containers.nix`:
|
||||
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
|
||||
{
|
||||
virtualisation.podman.enable = true;
|
||||
|
||||
# Define containers to auto-start
|
||||
virtualisation.podman.containers = {
|
||||
redis = {
|
||||
image = "redis:latest";
|
||||
ports = [ "6379:6379" ];
|
||||
autoStart = lib.mkDefault false;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Home Manager Customizations
|
||||
|
||||
### Add Starship Configuration
|
||||
|
||||
Edit `home/modules/shell.nix`:
|
||||
|
||||
```nix
|
||||
programs.starship = {
|
||||
enable = true;
|
||||
settings = {
|
||||
add_newline = true;
|
||||
character = {
|
||||
success_symbol = "[➜](bold green)";
|
||||
error_symbol = "[➜](bold red)";
|
||||
};
|
||||
rust = {
|
||||
disabled = false;
|
||||
symbol = "🦀 ";
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Add Zsh Plugins
|
||||
|
||||
Edit `home/modules/shell.nix`:
|
||||
|
||||
```nix
|
||||
programs.zsh.plugins = [
|
||||
{
|
||||
name = "zsh-autosuggestions";
|
||||
src = pkgs.fetchFromGitHub { /* ... */ };
|
||||
}
|
||||
{
|
||||
name = "powerlevel10k";
|
||||
src = pkgs.fetchFromGitHub { /* ... */ };
|
||||
file = "powerlevel10k.zsh-theme";
|
||||
}
|
||||
];
|
||||
```
|
||||
|
||||
### Add VSCode Configuration
|
||||
|
||||
Edit `home/modules/editor.nix`:
|
||||
|
||||
```nix
|
||||
programs.vscode = {
|
||||
enable = true;
|
||||
extensions = with pkgs.vscode-extensions; [
|
||||
ms-python.python
|
||||
rust-lang.rust-analyzer
|
||||
hashicorp.terraform
|
||||
];
|
||||
userSettings = {
|
||||
"editor.fontSize" = 14;
|
||||
"editor.formatOnSave" = true;
|
||||
"python.linting.enabled" = true;
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Add SSH Configuration
|
||||
|
||||
Create `home/modules/ssh.nix`:
|
||||
|
||||
```nix
|
||||
{ config, pkgs, ... }:
|
||||
|
||||
{
|
||||
programs.ssh = {
|
||||
enable = true;
|
||||
matchBlocks = {
|
||||
"github.com" = {
|
||||
host = "github.com";
|
||||
user = "git";
|
||||
identityFile = "~/.ssh/github";
|
||||
identitiesOnly = true;
|
||||
};
|
||||
"*.example.com" = {
|
||||
user = "myuser";
|
||||
identityFile = "~/.ssh/work";
|
||||
forwardAgent = true;
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Import in `home/default.nix`:
|
||||
```nix
|
||||
imports = [
|
||||
./modules/ssh.nix
|
||||
];
|
||||
```
|
||||
|
||||
### Add Tmux Configuration
|
||||
|
||||
Edit `home/modules/dev-tools.nix`:
|
||||
|
||||
```nix
|
||||
programs.tmux = {
|
||||
enable = true;
|
||||
mouse = true;
|
||||
baseIndex = 1;
|
||||
keyMode = "vi";
|
||||
|
||||
plugins = with pkgs.tmuxPlugins; [
|
||||
sensible
|
||||
vim-tmux-navigator
|
||||
resurrect
|
||||
];
|
||||
|
||||
extraConfig = ''
|
||||
# Custom keybindings
|
||||
bind -n M-h select-pane -L
|
||||
bind -n M-j select-pane -D
|
||||
bind -n M-k select-pane -U
|
||||
bind -n M-l select-pane -R
|
||||
'';
|
||||
};
|
||||
```
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### Using Unstable Packages Everywhere
|
||||
|
||||
In `home/modules/editor.nix`, use unstable neovim:
|
||||
|
||||
```nix
|
||||
{ pkgs, pkgs-unstable, ... }:
|
||||
|
||||
{
|
||||
programs.neovim = {
|
||||
enable = true;
|
||||
package = pkgs-unstable.neovim;
|
||||
# ...
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Conditional Configuration Based on Hardware
|
||||
|
||||
In `hosts/laptop/default.nix`:
|
||||
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
|
||||
{
|
||||
# Laptop-specific
|
||||
services.power-profiles-daemon.enable = true;
|
||||
services.logind.lidSwitchExternalPower = "ignore";
|
||||
|
||||
# Wireless
|
||||
networking.wireless.enable = true;
|
||||
|
||||
# Battery
|
||||
systemd.services.battery-monitor = {
|
||||
description = "Monitor battery health";
|
||||
wantedBy = [ "multi-user.target" ];
|
||||
script = "${pkgs.acpi}/bin/acpi";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Using Secrets in Home Manager
|
||||
|
||||
In `home/modules/example.nix`:
|
||||
|
||||
```nix
|
||||
{ config, sops-nix, ... }:
|
||||
|
||||
{
|
||||
imports = [ sops-nix.homeManagerModules.sops ];
|
||||
|
||||
sops.defaultSopsFile = ../../secrets/secrets.yaml;
|
||||
|
||||
sops.secrets."api/myapi" = {
|
||||
path = "%r/myapi"; # In ~/.config/sops-nix
|
||||
};
|
||||
|
||||
# Use in programs
|
||||
home.sessionVariables.MY_API_KEY = config.sops.secrets."api/myapi".path;
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Changes Safely
|
||||
|
||||
```bash
|
||||
# Build without applying
|
||||
home-manager build --flake .#myusername@linux
|
||||
|
||||
# Check what will change
|
||||
sudo nixos-rebuild test --flake .#laptop # Activates but doesn't add to boot
|
||||
|
||||
# Compare with current
|
||||
sudo nixos-rebuild diff --flake .#laptop
|
||||
|
||||
# Rollback if something breaks
|
||||
nixos-rebuild --rollback switch # NixOS
|
||||
home-manager switch --flake .#myusername@linux ~/.local/state/home-manager/current # HM
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Selective Updates
|
||||
|
||||
Update only specific inputs:
|
||||
```bash
|
||||
nix flake update nixpkgs
|
||||
nix flake update home-manager
|
||||
```
|
||||
|
||||
### Parallel Builds
|
||||
|
||||
In `flake.nix`, speed up evaluation:
|
||||
```bash
|
||||
NIX_BUILD_CORES=4 sudo nixos-rebuild switch --flake .#laptop
|
||||
```
|
||||
|
||||
### Binary Cache
|
||||
|
||||
Use nixpkgs binary cache:
|
||||
```nix
|
||||
# nixos/default.nix
|
||||
nix = {
|
||||
settings = {
|
||||
substituters = [ "https://cache.nixos.org" ];
|
||||
trusted-public-keys = [ "cache.nixos.org-1:6NCHdD59X431o0gWypQMvvZN1FSVucqL2mGvhiqHIl8=" ];
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
See QUICKREF.md for common operations reference.
|
||||
Reference in New Issue
Block a user