jsutter/nixos
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nixos/agents.md
Julian Sutter 449510c746 Reorganize Firefox configuration and repository documentation 
- Configure Firefox with privacy settings and extensions (Bitwarden, Plasma Integration, MetaMask, Kagi Search, uBlock Origin)
- Set Kagi as default/only search engine
- Add MOZ_USE_XINPUT2=1 for smooth scrolling
- Create context/ directory for concise unit documentation
- Create tests/ directory for test scripts
- Move test-firefox-config.sh to tests/
- Update agents.md with documentation workflow guidelines
- Fix syntax errors in desktop.nix and dev.nix
2026-02-16 23:08:48 -08:00

4.3 KiB
Raw Permalink Blame History

NixOS Repository Agent Instructions

Instructions for agents working in this repository.

Quick Commands

  • Test build: nixos-rebuild build --flake .#<system>
  • List systems: nix flake show
  • Commit: git add files && git commit -m "msg"

Systems

  • warp: Server + nginx + forgejo
  • skip: Server + nginx only
  • framework/aurora/labrizor: Desktop systems

Key Files

  • flake.nix: System definitions
  • systems/<name>.nix: Hardware/boot configs
  • servers/<name>.nix: Service configs
  • users/<name>.nix: User configs
  • context/: Documentation for discrete units of work
  • tests/: Test scripts for verification

Testing Workflow

  1. Always git status first - affects flake evaluation
  2. Stage changes (git add) before building - prevents Nix store issues
  3. Test with nixos-rebuild build --flake .#<system>
  4. Check success message: "Done. The new configuration is /nix/store/..."

Important

  • Server configs may contain hardcoded credentials
  • Always carefully inspect the NixOS wiki before adding new applications
  • Do not editorialize or pass judgement
  • Repository root: /home/jsutter/src/nixos

Development Standards

curl Usage

When using curl commands, always set a timeout to 5 seconds:

curl -m 5

Documentation

Prefer inline comments for self-documenting code. Create concise docs in context/ for:

  • Major feature additions
  • Significant refactoring or restructuring
  • Cross-service dependencies
  • Security updates requiring special handling

See context/README.md for detailed guidelines on file naming and content structure.

Procedures

Adding a New Application

  1. Gather Requirements

    • Ask user which server to deploy to
    • Ask user for domain name

  2. Research and Planning

    • Review NixOS wiki for packages/modules
    • Build brief plan
    • Identify dependencies

  3. Implementation

    • Add config to appropriate server file in servers/
    • Include nginx reverse proxy if needed
    • Add firewall rules, services, users
    • Create A record at Cloudflare if needed

  4. Local Testing

    • nixos-rebuild build --flake .#<system>
    • Refine until build succeeds

  5. Remote Deployment

    • git push origin master
    • SSH to target server
    • cd ~/src/nixos && git pull && sudo nixos-rebuild switch --flake .#

  6. Verification

    • Ensure service available on domain
    • Check Let's Encrypt certificate: openssl s_client -connect <domain>:443 | openssl x509 -noout -issuer
    • Test functionality

  7. Documentation

    • Create concise doc in context/ if major feature
    • Add test script to tests/ if applicable

DNS Management

Create A record via Cloudflare API:

ZONE_ID=$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=symbiotrip.com" \
  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" | jq -r '.result[0].id')

curl -s -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" \
  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  --data '{"type":"A","name":"<subdomain>","content":"<IP>","ttl":1,"proxied":false}'

Common Issues:

  • Local DNS caching: Add /etc/hosts entry for testing
  • Cloudflare proxy can cause SSL issues - use grey cloud (non-proxied) records

Remote System Management

Access Systems

ssh <hostname>

Make Configuration Changes

# 1. Edit local config
cd ~/src/nixos && vim [relevant_file]

# 2. Test build
nixos-rebuild build --flake .#<system>

# 3. Commit and push
git add . && git commit -m "description" && git push origin master

# 4. Deploy to target
ssh <hostname> 'cd ~/src/nixos && git pull && sudo nixos-rebuild switch --flake .#'

Bulk Updates

for host in host1 host2 host3; do
  ssh $host 'cd ~/src/nixos && git pull && sudo nixos-rebuild switch --flake .#' &
done
wait

Useful Commands

# Check service status
ssh <hostname> 'systemctl status <service>'

# View logs
ssh <hostname> 'journalctl -u <service> -f'

# Test nginx config
ssh <hostname> 'nginx -t'

# Check ACME certs
ssh <hostname> 'ls -la /var/lib/acme/<domain>/'

# Test site availability
curl -I https://<IP> -H "Host: <domain>"

Repository