449510c746
- 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
155 lines
No EOL
4.3 KiB
Markdown
155 lines
No EOL
4.3 KiB
Markdown
# 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 |