# 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:
```bash
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:
```bash
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
```bash
ssh <hostname>
```

### Make Configuration Changes
```bash
# 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
```bash
for host in host1 host2 host3; do
  ssh $host 'cd ~/src/nixos && git pull && sudo nixos-rebuild switch --flake .#' &
done
wait
```

### Useful Commands
```bash
# 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
- **Central**: https://git.symbiotrip.com/jsutter/nixos
- **Update workflow**: Local edit → Push → Remote pull → Rebuild