Getting Started

Welcome to your Nix configuration! This section will get you up and running quickly.

Brand new to this config? → Quickstart (5 minutes)

Want detailed setup? → Installation Guide

Already installed? → First Steps

Documentation in This Section

Quickstart

Get up and running in 5 minutes with essential commands and quick setup.

Perfect for:

First-time users who want to get started fast
Experienced Nix users who just need the basics
Quick reference for installation steps

Installation Guide

Comprehensive installation instructions with detailed explanations.

Covers:

Prerequisites and system requirements
Step-by-step Nix installation
Customizing for your machine
Troubleshooting common issues
Verification steps

First Steps

Learn how to use and customize your newly installed system.

Learn to:

Add and remove packages
Customize your shell
Work with profiles and modules
Manage secrets with SOPS
Daily workflow patterns

Installation Overview

┌─────────────────────────────────────────────────────────────┐
│                    Installation Flow                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Install Nix                                             │
│     ↓                                                       │
│  2. Install Homebrew (macOS GUI apps)                       │
│     ↓                                                       │
│  3. Clone this configuration                                │
│     ↓                                                       │
│  4. Customize for your machine                              │
│     ↓                                                       │
│  5. Apply configuration                                     │
│     ↓                                                       │
│  6. Enjoy your reproducible system!                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

What You Get

After installation, you’ll have:

System Configuration

✅ Nix package manager with flakes
✅ nix-darwin for system management
✅ Home Manager for user environment
✅ Homebrew for macOS GUI apps

Installed Tools

✅ Development utilities (git, vim, curl, jq, tree)
✅ Cloud CLIs (AWS, GCP, Kubernetes, Terraform)
✅ Container tools (Colima, Docker, Skopeo, Dive)
✅ AI tools (Claude Code, MCP Inspector)

Optional Features

⭐ Ledger hardware wallet support
⭐ GPG signing with hardware key
⭐ SSH authentication with Ledger
⭐ SOPS secrets management

Prerequisites

Before you begin, you need:

macOS 11 (Big Sur) or later
10 GB free disk space
Administrator access (sudo)
Terminal app
Optional: Ledger Nano S for hardware security

Quick Start Commands

# 1. Install Nix (Determinate Systems)
curl -fsSL https://install.determinate.systems/nix | sh -s -- install --determinate

# 2. Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 3. Clone config
git clone https://github.com/yourusername/Config.git ~/Config
cd ~/Config

# 4. First-time setup
sudo nix run nix-darwin -- switch --flake .#wikigen-mac

# 5. Subsequent updates
darwin-rebuild switch --flake .#wikigen-mac

See Quickstart for details.

After Installation

Essential Next Steps

First Steps - Learn daily workflow
Ledger Setup - Configure hardware wallet
SOPS Setup - Set up secrets

Learn the System

Structure Guide - Understand the architecture
Design Philosophy - Learn design decisions
Nix Fundamentals - Deep dive into Nix

Customize Further

Adding Packages - Install software
Creating Modules - Write modules
Creating Profiles - Build profiles

Common Questions

Which installer should I use?

Recommended: Determinate Systems installer

Flakes enabled by default
Better macOS support
Optimized for modern Nix

Alternative: Official installer

More conservative
Requires manual flake configuration

See Installation Guide for details.

Do I need Homebrew?

Yes, for macOS-specific GUI applications:

Ledger Live
Other cask-only apps

Nix handles all CLI tools and libraries.

Can I use this on Linux?

Yes! This config supports:

✅ macOS (Darwin) - Current focus
🚧 Linux (NixOS) - Planned
🚧 Cloud (EC2/GCE) - Planned

See Design Doc for roadmap.

How do I update my system?

# Update dependencies
nix flake update

# Apply changes
darwin-rebuild switch --flake .#your-hostname

See First Steps for workflow details.

Troubleshooting

Having issues? Check these resources:

Troubleshooting Guide - Common problems
Installation Guide - Install-specific issues
CLI Commands - Command reference
NixOS Discourse - Community help

In This Section

Quickstart - 5-minute setup
Installation - Detailed install guide
First Steps - Post-install guide

Next Sections

Architecture - Understanding the design
Guides - How-to guides for specific tasks
Reference - Technical references
Examples - Practical examples

Get Help

Documentation: docs/README.md
Issues: Report bugs on GitHub
Community: NixOS Discourse
Wiki: NixOS Wiki

Ready to begin? Start with the Quickstart Guide!