From d77a84b2e920a8d952d4d43af62a87df47264f53 Mon Sep 17 00:00:00 2001 From: Danilo Reyes Date: Thu, 2 Oct 2025 22:56:56 -0600 Subject: [PATCH] readme --- README.org | 239 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 README.org diff --git a/README.org b/README.org new file mode 100644 index 0000000..acd0ba4 --- /dev/null +++ b/README.org @@ -0,0 +1,239 @@ +#+TITLE: JawZ NixOS Configuration +#+AUTHOR: JawZ +#+EMAIL: CaptainJawZ@protonmail.com +#+OPTIONS: toc:t num:t +#+STARTUP: content + +* 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. + +* Architecture + +** 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 + +** 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 + +* Quick Start + +** Prerequisites +- NixOS 23.05 or later +- SOPS configured with age keys +- SSH keys for remote builds + +** Initial Setup +#+BEGIN_SRC bash +# Clone the repository git clone /home/jawz/Development/NixOS +cd /home/jawz/Development/NixOS + +# Install dependencies nix flake update + +# Build and switch to configuration sudo nixos-rebuild switch --flake +.# +#+END_SRC + +** Development Environment +#+BEGIN_SRC bash +# Enter development shell for specific language nix develop .# + +# Available languages: python, rust, go, haskell, javascript, julia, zig, sh, +cc, nix +#+END_SRC + +* Configuration Structure + +** 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 + +** Host Configurations +- =hosts//configuration.nix= :: Host-specific settings +- =hosts//hardware-configuration.nix= :: Hardware-specific config +- =hosts//toggles.nix= :: Feature toggles + +** 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 + +* 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 +- Check service-specific documentation + +* Maintenance + +** Regular Tasks +- Update flake inputs weekly +- Review and rotate secrets quarterly +- Update system packages monthly +- Clean old generations: =sudo nix-collect-garbage -d= + +** Backup Strategy +- Configuration is version controlled +- Secrets are encrypted and backed up +- BTRFS snapshots for data protection + +* Contributing + +** Code Style +- Use consistent formatting +- Add comments for complex configurations +- Follow Nix conventions + +** Pull Requests +- Test changes on development host first +- Update documentation as needed +- Ensure all secrets are properly managed + +* License + +This configuration is for personal use. Please respect the licenses of +individual packages and services used. + +* Contact + +For questions or issues, contact CaptainJawZ@protonmail.com + +--- + +*Last updated: 2025*