new readme
This commit is contained in:
Danilo Reyes
230
README.org
230
README.org
@@ -6,198 +6,72 @@
|
|||||||
|
|
||||||
* Overview
|
* Overview
|
||||||
|
|
||||||
This repository contains my personal NixOS configuration flake, managing
|
This repository is a NixOS configuration flake with a local MCP server
|
||||||
multiple hosts with a modular approach. Designed the configuration for a
|
(`nixos-mcp`) that helps Codex CLI work with the repo’s documentation and
|
||||||
self-hosted infrastructure with services and development environments.
|
maintenance workflows. The README focuses on how to use the MCP server and
|
||||||
|
how the repo is structured.
|
||||||
|
|
||||||
* Architecture
|
* MCP Server (nixos-mcp)
|
||||||
|
|
||||||
** Hosts
|
** What it is
|
||||||
- =workstation= :: Main development machine with GNOME desktop
|
Local-only MCP server that exposes repo documentation helpers over stdio so
|
||||||
- =server= :: Primary server with containerized services
|
Codex CLI can read the constitution, playbooks, and reference map without
|
||||||
- =miniserver= :: Secondary server for additional services
|
manual navigation.
|
||||||
- =galaxy= :: Minimal configuration host
|
|
||||||
- =emacs= :: Development VM for Emacs configuration
|
|
||||||
|
|
||||||
** Key Features
|
** Tool Catalog
|
||||||
- Modular configuration system
|
- =show-constitution= :: Open =docs/constitution.md=
|
||||||
- SOPS-based secrets management
|
- =list-playbooks= :: List =docs/playbooks/=
|
||||||
- Container orchestration with Podman
|
- =show-reference= :: Open =docs/reference/index.md=
|
||||||
- Automated builds and caching
|
- =search-docs= :: Search the docs set
|
||||||
- Multi-language development environments
|
- =list-mcp-tasks= :: Show MCP tasks from =specs/002-mcp-server/tasks.md=
|
||||||
- Self-hosted service stack
|
- =sync-docs= :: Check tool catalog vs. docs anchors
|
||||||
|
|
||||||
* Quick Start
|
** Quick Start (new users)
|
||||||
|
|
||||||
** Prerequisites
|
|
||||||
- NixOS 23.05 or later
|
|
||||||
- SOPS configured with age keys
|
|
||||||
- SSH keys for remote builds
|
|
||||||
|
|
||||||
** Initial Setup
|
|
||||||
#+BEGIN_SRC bash
|
#+BEGIN_SRC bash
|
||||||
# Clone the repository git clone <repository-url> /home/jawz/Development/NixOS
|
# Enter the MCP dev shell (includes codex + nixos-mcp)
|
||||||
cd /home/jawz/Development/NixOS
|
nix develop .#mcp
|
||||||
|
|
||||||
# Install dependencies nix flake update
|
# Run the MCP server (stdio mode)
|
||||||
|
nixos-mcp
|
||||||
# Build and switch to configuration sudo nixos-rebuild switch --flake
|
|
||||||
.#<hostname>
|
|
||||||
#+END_SRC
|
#+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
|
** Reference
|
||||||
#+BEGIN_SRC bash
|
Detailed invocation notes live in =docs/reference/mcp-server.md=.
|
||||||
# Enter development shell for specific language nix develop .#<language>
|
|
||||||
|
|
||||||
# Available languages: python, rust, go, haskell, javascript, julia, zig, sh,
|
* Repository Structure
|
||||||
cc, nix
|
|
||||||
#+END_SRC
|
|
||||||
|
|
||||||
* 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
|
** MCP Server
|
||||||
- =config/base.nix= :: Common system configuration
|
- =scripts/mcp-server/= :: Python MCP server implementation, tests, and CLI
|
||||||
- =config/jawz.nix= :: User and SSH configuration
|
- =modules/dev/mcp.nix= :: Dev shell and optional global install
|
||||||
- =config/stylix.nix= :: Theming configuration
|
|
||||||
- =config/schemes.nix= :: Color scheme definitions
|
|
||||||
|
|
||||||
** Host Configurations
|
** Flake Parts
|
||||||
- =hosts/<hostname>/configuration.nix= :: Host-specific settings
|
- =parts/core.nix= :: Shared library + base composition
|
||||||
- =hosts/<hostname>/hardware-configuration.nix= :: Hardware-specific config
|
- =parts/hosts.nix= :: Host definitions
|
||||||
- =hosts/<hostname>/toggles.nix= :: Feature toggles
|
- =parts/packages.nix= :: Package outputs
|
||||||
|
- =parts/devshells.nix= :: Dev shells (including MCP)
|
||||||
|
|
||||||
** Modules
|
* Flake Inputs (high level)
|
||||||
- =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
|
|
||||||
|
|
||||||
* Services
|
** Core Inputs
|
||||||
|
- =nixpkgs= (25.11) and =nixpkgs-small= (25.11-small)
|
||||||
** Core Services
|
- =nixpkgs-unstable= (rolling)
|
||||||
- PostgreSQL 17 :: Database backend
|
- =flake-parts= (structure)
|
||||||
- Nginx :: Reverse proxy and web server
|
- =home-manager= (user configs)
|
||||||
- Podman :: Container runtime
|
- =stylix= (theming)
|
||||||
- Syncthing :: File synchronization
|
- =sops-nix= (secrets integration)
|
||||||
- WireGuard :: VPN connectivity
|
- =nur=, =nix-gaming=, =hyprland= (extra packages)
|
||||||
|
- Content inputs: =wallpapers=, =fonts=, =qbit_manage=
|
||||||
** Self-Hosted Applications
|
- Repo inputs: =jawz-scripts=, =prem2resolve=, =lidarr-mb-gap=
|
||||||
- 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/<hostname>/
|
|
||||||
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 <service>=
|
|
||||||
- View logs: =journalctl -u <service>=
|
|
||||||
- Verify firewall rules
|
|
||||||
|
|
||||||
*** Development Environment
|
|
||||||
- Rebuild development shell: =nix develop .#<language>=
|
|
||||||
- Check available packages: =nix search nixpkgs <package>=
|
|
||||||
|
|
||||||
** Getting Help
|
|
||||||
- Check NixOS documentation
|
|
||||||
- Review module documentation
|
|
||||||
- Check service-specific documentation
|
- Check service-specific documentation
|
||||||
|
|
||||||
* Maintenance
|
* Maintenance
|
||||||
|
|||||||
Reference in New Issue
Block a user