fixes and docs
This commit is contained in:
mjallen18
@@ -6,167 +6,170 @@ This guide will help you get started with this NixOS configuration repository.
|
||||
|
||||
- Basic knowledge of NixOS and the Nix language
|
||||
- Git installed on your system
|
||||
- Physical access to the machine you want to configure
|
||||
- Physical or SSH access to the target machine
|
||||
|
||||
## Initial Setup
|
||||
|
||||
### 1. Cloning the Repository
|
||||
|
||||
Clone this repository to your local machine:
|
||||
## Cloning the Repository
|
||||
|
||||
```bash
|
||||
git clone ssh://nix-apps@localhost:2222/mjallen/nix-config.git
|
||||
cd nix-config
|
||||
```
|
||||
|
||||
### 2. Setting Up a New System
|
||||
## Installing on a New Machine
|
||||
|
||||
#### Option 1: Using an Existing Configuration
|
||||
### Option 1: Using an existing system configuration
|
||||
|
||||
If you're setting up a new machine that should be identical to an existing configuration:
|
||||
If the machine matches an existing configuration (e.g. reinstalling `jallen-nas`):
|
||||
|
||||
1. Boot from a NixOS installation media
|
||||
2. Mount your target partitions to `/mnt`
|
||||
3. Clone this repository:
|
||||
1. Boot from a NixOS installation ISO
|
||||
2. Partition and mount disks (or use `disko`):
|
||||
```bash
|
||||
nixos-enter
|
||||
cd /mnt
|
||||
mkdir -p /mnt/etc/nixos
|
||||
git clone ssh://nix-apps@localhost:2222/mjallen/nix-config.git /mnt/etc/nixos
|
||||
nix run github:nix-community/disko -- --mode disko /path/to/disko-config.nix
|
||||
```
|
||||
4. Install NixOS with the desired system profile:
|
||||
3. Clone this repo into the target:
|
||||
```bash
|
||||
mkdir -p /mnt/etc/nixos
|
||||
git clone <repo-url> /mnt/etc/nixos
|
||||
```
|
||||
4. Install:
|
||||
```bash
|
||||
nixos-install --flake /mnt/etc/nixos#hostname
|
||||
```
|
||||
Replace `hostname` with the target system name (e.g., `matt-nixos`, `jallen-nas`, etc.)
|
||||
|
||||
#### Option 2: Creating a New System Configuration
|
||||
### Option 2: Adding a new system configuration
|
||||
|
||||
If you're adding a completely new system:
|
||||
|
||||
1. Create a new directory for your system configuration:
|
||||
1. **Create the system directory** under the appropriate architecture:
|
||||
```bash
|
||||
mkdir -p systems/$(uname -m)-linux/new-hostname
|
||||
mkdir -p systems/x86_64-linux/new-hostname
|
||||
```
|
||||
|
||||
2. Create the basic configuration files:
|
||||
```bash
|
||||
cat > systems/$(uname -m)-linux/new-hostname/default.nix << EOF
|
||||
{ lib, pkgs, ... }:
|
||||
|
||||
2. **Write the configuration** — at minimum a `default.nix`:
|
||||
```nix
|
||||
{ namespace, ... }:
|
||||
{
|
||||
imports = [
|
||||
./hardware-configuration.nix
|
||||
# Add other needed module imports here
|
||||
];
|
||||
|
||||
networking.hostName = "new-hostname";
|
||||
|
||||
# Add your system-specific configuration here
|
||||
mjallen = {
|
||||
sops.enable = true;
|
||||
network.hostName = "new-hostname";
|
||||
user.name = "admin";
|
||||
};
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
3. Generate the hardware configuration:
|
||||
3. **Generate hardware configuration** (on the target machine):
|
||||
```bash
|
||||
nixos-generate-config --no-filesystems --dir systems/$(uname -m)-linux/new-hostname/
|
||||
nixos-generate-config --no-filesystems --dir systems/x86_64-linux/new-hostname/
|
||||
```
|
||||
|
||||
4. Add your new system to the flake by adding it to the `hosts` section in `flake.nix`
|
||||
4. **Add SOPS secrets** for the new host — see [Secrets Management](../README.md#secrets-management).
|
||||
|
||||
5. Build and install the configuration:
|
||||
5. **Build and switch**:
|
||||
```bash
|
||||
sudo nixos-rebuild switch --flake .#new-hostname
|
||||
```
|
||||
|
||||
## Secret Management
|
||||
## Day-to-Day Usage
|
||||
|
||||
### Setting Up Sops-Nix
|
||||
|
||||
1. Create a GPG key if you don't already have one:
|
||||
```bash
|
||||
gpg --full-generate-key
|
||||
```
|
||||
|
||||
2. Add your key to `.sops.yaml`:
|
||||
```bash
|
||||
# Get your key fingerprint
|
||||
gpg --list-secret-keys --keyid-format=long
|
||||
|
||||
# Edit the .sops.yaml file to add your key
|
||||
```
|
||||
|
||||
3. Create a new encrypted secret:
|
||||
```bash
|
||||
sops secrets/newsecret.yaml
|
||||
```
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Updating the Repository
|
||||
### Applying configuration changes
|
||||
|
||||
```bash
|
||||
git pull
|
||||
sudo nixos-rebuild switch --flake .#hostname
|
||||
# On the local machine
|
||||
sudo nixos-rebuild switch --flake .#$(hostname)
|
||||
|
||||
# On a remote machine
|
||||
nixos-rebuild switch --flake .#hostname --target-host user@host --use-remote-sudo
|
||||
```
|
||||
|
||||
### Adding a New Package
|
||||
### Updating flake inputs
|
||||
|
||||
1. For standard packages, add them to your system or home configuration:
|
||||
```bash
|
||||
# Update all inputs
|
||||
nix flake update
|
||||
|
||||
# Update a single input
|
||||
nix flake lock --update-input nixpkgs
|
||||
|
||||
# Apply after updating
|
||||
sudo nixos-rebuild switch --flake .#$(hostname)
|
||||
```
|
||||
|
||||
### Garbage collection
|
||||
|
||||
```bash
|
||||
# Remove old generations and unreferenced store paths
|
||||
sudo nix-collect-garbage -d
|
||||
|
||||
# Keep the last N generations
|
||||
sudo nix-collect-garbage --delete-older-than 30d
|
||||
```
|
||||
|
||||
## Enabling a Module
|
||||
|
||||
Most functionality is exposed through the `mjallen` namespace. To enable a module, set it in the system's `default.nix` (or a relevant sub-file):
|
||||
|
||||
```nix
|
||||
mjallen = {
|
||||
desktop.gnome.enable = true;
|
||||
hardware.amd.enable = true;
|
||||
gaming.enable = true;
|
||||
|
||||
services.jellyfin = {
|
||||
enable = true;
|
||||
port = 8096;
|
||||
reverseProxy.enable = true;
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
See [Custom Modules](./modules/README.md) for the full list of available modules and options.
|
||||
|
||||
## Adding a New Service Module
|
||||
|
||||
1. **Create the module directory**:
|
||||
```bash
|
||||
mkdir -p modules/nixos/services/my-service
|
||||
```
|
||||
|
||||
2. **Write `default.nix`** using the `mkModule` helper:
|
||||
```nix
|
||||
environment.systemPackages = with pkgs; [
|
||||
new-package
|
||||
];
|
||||
```
|
||||
|
||||
2. For custom packages, add them to the `packages` directory:
|
||||
```bash
|
||||
mkdir -p packages/new-package
|
||||
# Create the necessary Nix files
|
||||
```
|
||||
|
||||
### Adding a New Module
|
||||
|
||||
1. Create a new module directory:
|
||||
```bash
|
||||
mkdir -p modules/nixos/new-module
|
||||
```
|
||||
|
||||
2. Create the module files:
|
||||
```bash
|
||||
# Create options.nix
|
||||
cat > modules/nixos/new-module/options.nix << EOF
|
||||
{ lib, namespace, ... }:
|
||||
with lib;
|
||||
{
|
||||
options.${namespace}.new-module = {
|
||||
enable = mkEnableOption "Enable new module";
|
||||
# Add other options here
|
||||
};
|
||||
}
|
||||
EOF
|
||||
|
||||
# Create default.nix
|
||||
cat > modules/nixos/new-module/default.nix << EOF
|
||||
{ config, lib, namespace, ... }:
|
||||
{ config, lib, namespace, pkgs, ... }:
|
||||
let
|
||||
cfg = config.${namespace}.new-module;
|
||||
in
|
||||
{
|
||||
imports = [ ./options.nix ];
|
||||
|
||||
config = lib.mkIf cfg.enable {
|
||||
# Add your configuration here
|
||||
name = "my-service";
|
||||
nebulaConfig = lib.${namespace}.mkModule {
|
||||
inherit config name;
|
||||
description = "my service description";
|
||||
options = { };
|
||||
moduleConfig = {
|
||||
services.my-service = {
|
||||
enable = true;
|
||||
port = config.${namespace}.services.${name}.port;
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
EOF
|
||||
in
|
||||
{ imports = [ nebulaConfig ]; }
|
||||
```
|
||||
|
||||
3. Import your module in your system configuration:
|
||||
3. **Enable it** in a system configuration:
|
||||
```nix
|
||||
imports = [
|
||||
# ...
|
||||
../../../modules/nixos/new-module
|
||||
];
|
||||
|
||||
${namespace}.new-module.enable = true;
|
||||
```
|
||||
mjallen.services.my-service = {
|
||||
enable = true;
|
||||
port = 1234;
|
||||
};
|
||||
```
|
||||
|
||||
## Adding a New Package
|
||||
|
||||
1. Create a directory under `packages/`:
|
||||
```bash
|
||||
mkdir packages/my-package
|
||||
```
|
||||
|
||||
2. Write a `default.nix` that returns a derivation. The package will be available as `pkgs.mjallen.my-package` in all configurations.
|
||||
|
||||
## Secrets
|
||||
|
||||
See the [Secrets Management](../README.md#secrets-management) section of the root README for:
|
||||
- How age keys are derived from SSH host keys
|
||||
- Adding a new machine as a SOPS recipient
|
||||
- Adding/editing secrets
|
||||
- Generating Nebula VPN certificates
|
||||
|
||||
Reference in New Issue
Block a user