From 480c9a2a07c68b58282d99ecd71a5892d6665213 Mon Sep 17 00:00:00 2001 From: Danilo Reyes Date: Fri, 6 Feb 2026 20:09:52 -0600 Subject: [PATCH] new readme --- README.org | 230 ++++++++++++----------------------------------------- 1 file changed, 52 insertions(+), 178 deletions(-) diff --git a/README.org b/README.org index 153ab08..424754b 100644 --- a/README.org +++ b/README.org @@ -6,198 +6,72 @@ * Overview -This repository contains my personal NixOS configuration flake, managing -multiple hosts with a modular approach. Designed the configuration for a -self-hosted infrastructure with services and development environments. +This repository is a NixOS configuration flake with a local MCP server +(`nixos-mcp`) that helps Codex CLI work with the repo’s documentation and +maintenance workflows. The README focuses on how to use the MCP server and +how the repo is structured. -* Architecture +* MCP Server (nixos-mcp) -** Hosts -- =workstation= :: Main development machine with GNOME desktop -- =server= :: Primary server with containerized services -- =miniserver= :: Secondary server for additional services -- =galaxy= :: Minimal configuration host -- =emacs= :: Development VM for Emacs configuration +** What it is +Local-only MCP server that exposes repo documentation helpers over stdio so +Codex CLI can read the constitution, playbooks, and reference map without +manual navigation. -** Key Features -- Modular configuration system -- SOPS-based secrets management -- Container orchestration with Podman -- Automated builds and caching -- Multi-language development environments -- Self-hosted service stack +** Tool Catalog +- =show-constitution= :: Open =docs/constitution.md= +- =list-playbooks= :: List =docs/playbooks/= +- =show-reference= :: Open =docs/reference/index.md= +- =search-docs= :: Search the docs set +- =list-mcp-tasks= :: Show MCP tasks from =specs/002-mcp-server/tasks.md= +- =sync-docs= :: Check tool catalog vs. docs anchors -* Quick Start - -** Prerequisites -- NixOS 23.05 or later -- SOPS configured with age keys -- SSH keys for remote builds - -** Initial Setup +** Quick Start (new users) #+BEGIN_SRC bash -# Clone the repository git clone /home/jawz/Development/NixOS -cd /home/jawz/Development/NixOS +# Enter the MCP dev shell (includes codex + nixos-mcp) +nix develop .#mcp -# Install dependencies nix flake update - -# Build and switch to configuration sudo nixos-rebuild switch --flake -.# +# Run the MCP server (stdio mode) +nixos-mcp #+END_SRC +Configure Codex CLI to use a local stdio MCP endpoint and allowlist +=nixos-mcp= in =.codex/requirements.toml=. The dev shell sets +=CODEX_HOME=.codex= for a repo-local Codex config. -** Development Environment -#+BEGIN_SRC bash -# Enter development shell for specific language nix develop .# +** Reference +Detailed invocation notes live in =docs/reference/mcp-server.md=. -# Available languages: python, rust, go, haskell, javascript, julia, zig, sh, -cc, nix -#+END_SRC +* Repository Structure -* Configuration Structure +** Docs and Guidance +- =docs/constitution.md= :: AI constitution (authoritative rules) +- =docs/reference/index.md= :: Reference map +- =docs/reference/mcp-server.md= :: MCP server reference +- =docs/playbooks/= :: Repeatable workflows +- =specs/002-mcp-server/= :: MCP feature plan + tasks -** Core Configuration -- =config/base.nix= :: Common system configuration -- =config/jawz.nix= :: User and SSH configuration -- =config/stylix.nix= :: Theming configuration -- =config/schemes.nix= :: Color scheme definitions +** MCP Server +- =scripts/mcp-server/= :: Python MCP server implementation, tests, and CLI +- =modules/dev/mcp.nix= :: Dev shell and optional global install -** Host Configurations -- =hosts//configuration.nix= :: Host-specific settings -- =hosts//hardware-configuration.nix= :: Hardware-specific config -- =hosts//toggles.nix= :: Feature toggles +** Flake Parts +- =parts/core.nix= :: Shared library + base composition +- =parts/hosts.nix= :: Host definitions +- =parts/packages.nix= :: Package outputs +- =parts/devshells.nix= :: Dev shells (including MCP) -** Modules -- =modules/apps/= :: Application packages and configurations -- =modules/dev/= :: Development environment modules -- =modules/servers/= :: Self-hosted service configurations -- =modules/services/= :: System service configurations -- =modules/scripts/= :: Custom scripts and utilities -- =modules/shell/= :: Shell and terminal configurations +* Flake Inputs (high level) -* Services - -** Core Services -- PostgreSQL 17 :: Database backend -- Nginx :: Reverse proxy and web server -- Podman :: Container runtime -- Syncthing :: File synchronization -- WireGuard :: VPN connectivity - -** Self-Hosted Applications -- Nextcloud :: File sharing and collaboration -- Gitea :: Git repository hosting -- Jellyfin :: Media server -- Plex :: Media streaming -- Sonarr/Radarr/Lidarr :: Media management -- Vaultwarden :: Password manager -- Homepage :: Service dashboard -- And more... - -* Development - -** Available Development Shells -The configuration provides development shells for my favorite programming -languages: - -#+BEGIN_SRC bash -# Python development nix develop .#python - -# Rust development nix develop .#rust - -# Go development nix develop .#go - -# JavaScript/Node.js development nix develop .#javascript - -# Haskell development nix develop .#haskell - -# Julia development nix develop .#julia - -# Zig development nix develop .#zig - -# Shell scripting nix develop .#sh - -# C/C++ development nix develop .#cc - -# Nix development nix develop .#nix -#+END_SRC - -** Adding New Modules -1. Create module file in appropriate directory under =modules/= -2. Add module to =modules/modules.nix= if needed -3. Enable module in host configuration or toggles - -** Adding New Hosts -1. Create host directory under =hosts// -2. Add =configuration.nix= and =hardware-configuration.nix= -3. Add host to =flake.nix= outputs -4. Create =toggles.nix= for feature management - -* Secrets Management - -** SOPS Configuration -Manage secrets using SOPS with age encryption: - -- =secrets/secrets.yaml= :: Main secrets file -- =secrets/keys.yaml= :: SSH and encryption keys -- =secrets/env.yaml= :: Environment variables -- =secrets/wireguard.yaml= :: VPN configuration -- =secrets/certs.yaml= :: SSL certificates - -** Adding New Secrets -#+BEGIN_SRC bash -# Edit secrets file sops secrets/secrets.yaml - -# Add new secret sops -i -a 'new-secret: "value"' secrets/secrets.yaml -#+END_SRC - -* CI/CD - -** GitHub Actions -The repository includes automated workflows: - -- =weekly-build-cache.yml= :: Weekly builds and cache updates -- =build-schemes.yml= :: Color scheme builds - -** Build Cache -Builds are automatically cached using Atticd for faster rebuilds. - - -* Customization - -** Theming -The configuration uses Stylix for theming. Define color schemes in -=config/schemes.nix= and can set them via the =config/stylix.nix= file. - -** Adding New Services -1. Create service module in =modules/servers/= -2. Add service configuration -3. Enable service in host toggles -4. Add to homepage if needed - -** Custom Scripts -Scripts are in =modules/scripts/= and toggle them per host. - -* Troubleshooting - -** Common Issues - -*** Build Failures -- Check flake inputs are up to date: =nix flake update= -- Verify all required secrets are present -- Check host-specific configuration - -*** Service Issues -- Check service status: =systemctl status = -- View logs: =journalctl -u = -- Verify firewall rules - -*** Development Environment -- Rebuild development shell: =nix develop .#= -- Check available packages: =nix search nixpkgs = - -** Getting Help -- Check NixOS documentation -- Review module documentation +** Core Inputs +- =nixpkgs= (25.11) and =nixpkgs-small= (25.11-small) +- =nixpkgs-unstable= (rolling) +- =flake-parts= (structure) +- =home-manager= (user configs) +- =stylix= (theming) +- =sops-nix= (secrets integration) +- =nur=, =nix-gaming=, =hyprland= (extra packages) +- Content inputs: =wallpapers=, =fonts=, =qbit_manage= +- Repo inputs: =jawz-scripts=, =prem2resolve=, =lidarr-mb-gap= - Check service-specific documentation * Maintenance