readme
This commit is contained in:
parent
ab22bef7b4
commit
d77a84b2e9
239
README.org
Normal file
239
README.org
Normal file
@ -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 <repository-url> /home/jawz/Development/NixOS
|
||||
cd /home/jawz/Development/NixOS
|
||||
|
||||
# Install dependencies nix flake update
|
||||
|
||||
# Build and switch to configuration sudo nixos-rebuild switch --flake
|
||||
.#<hostname>
|
||||
#+END_SRC
|
||||
|
||||
** Development Environment
|
||||
#+BEGIN_SRC bash
|
||||
# Enter development shell for specific language nix develop .#<language>
|
||||
|
||||
# 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/<hostname>/configuration.nix= :: Host-specific settings
|
||||
- =hosts/<hostname>/hardware-configuration.nix= :: Hardware-specific config
|
||||
- =hosts/<hostname>/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/<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
|
||||
|
||||
* 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*
|
||||
Loading…
x
Reference in New Issue
Block a user