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
This commit is contained in:
Julian Sutter
parent
67581adde6
commit
449510c746
10 changed files with 994 additions and 111 deletions
182
agents.md
182
agents.md
|
|
@ -1,9 +1,11 @@
|
|||
# NixOS Repository Quick Reference
|
||||
# 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"`
|
||||
- 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
|
||||
|
|
@ -15,6 +17,8 @@
|
|||
- `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
|
||||
|
|
@ -24,141 +28,111 @@
|
|||
|
||||
## Important
|
||||
- Server configs may contain hardcoded credentials
|
||||
- Always carefully inspect the NixOS wiki for instructions before adding new applications to the repo
|
||||
- Do not editorialize or pass judgement. Be a robot.
|
||||
- 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 to the Repository
|
||||
### Adding a New Application
|
||||
|
||||
1. **Gather Requirements**
|
||||
- Ask the user what server to deploy to
|
||||
- Ask the user what domain name the app will be available on
|
||||
- Ask user which server to deploy to
|
||||
- Ask user for domain name
|
||||
|
||||
2. **Research and Planning**
|
||||
- Build a brief plan to construct the app
|
||||
- Review the NixOS wiki (https://nixos.org/nixos/manual/) to see if packages are available
|
||||
- Check for existing NixOS modules or services that can be used
|
||||
- Identify dependencies and configuration requirements
|
||||
- Review NixOS wiki for packages/modules
|
||||
- Build brief plan
|
||||
- Identify dependencies
|
||||
|
||||
3. **Implementation**
|
||||
- Follow the plan constructed in step 2
|
||||
- Add the necessary configuration to the appropriate server file in `servers/`
|
||||
- Include nginx reverse proxy configuration if the app needs to be accessible via HTTP/HTTPS
|
||||
- Add any required firewall rules, services, or users
|
||||
- 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**
|
||||
- Test the build locally: `nixos-rebuild build --flake .#<system>`
|
||||
- Refine the configuration until the build succeeds
|
||||
- Review the generated configuration for correctness
|
||||
- `nixos-rebuild build --flake .#<system>`
|
||||
- Refine until build succeeds
|
||||
|
||||
5. **Remote Deployment**
|
||||
- Push the repo to the remote machine: `git push origin master`
|
||||
- SSH to the target server
|
||||
- Pull the changes: `cd ~/src/nixos && git pull origin master`
|
||||
- Build and switch to the new config: `sudo nixos-rebuild switch --flake .#`
|
||||
- `git push origin master`
|
||||
- SSH to target server
|
||||
- `cd ~/src/nixos && git pull && sudo nixos-rebuild switch --flake .#`
|
||||
|
||||
6. **Verification**
|
||||
- Ensure the service is available on the chosen domain
|
||||
- Ensure the certificate is issued by Let's Encrypt (check with: `openssl s_client -connect <domain>:443 | openssl x509 -noout -issuer`)
|
||||
- Test basic functionality of the application
|
||||
- Ensure service available on domain
|
||||
- Check Let's Encrypt certificate: `openssl s_client -connect <domain>:443 | openssl x509 -noout -issuer`
|
||||
- Test functionality
|
||||
|
||||
7. **Troubleshooting**
|
||||
- If the app isn't available on the chosen domain:
|
||||
- Check service status: `systemctl status <service>`
|
||||
- Check nginx logs: `journalctl -u nginx -f`
|
||||
- Check application logs: `journalctl -u <service> -f`
|
||||
- Verify DNS resolution
|
||||
- Check firewall rules
|
||||
- Verify nginx configuration syntax: `nginx -t`
|
||||
- If the certificate isn't issued by Let's Encrypt:
|
||||
- Check ACME challenge configuration
|
||||
- Verify domain ownership record
|
||||
- Check Let's Encrypt logs: `journalctl -u certbot -f`
|
||||
- Manually trigger certificate renewal if needed
|
||||
7. **Documentation**
|
||||
- Create concise doc in `context/` if major feature
|
||||
- Add test script to `tests/` if applicable
|
||||
|
||||
### DNS Management
|
||||
|
||||
#### Create DNS Record via Cloudflare API
|
||||
```bash
|
||||
# Get zone ID for domain
|
||||
ZONE_ID=$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=symbiotrip.com" \
|
||||
-H "Authorization: Bearer <CLOUDFLARE_API_TOKEN>" \
|
||||
-H "Content-Type: application/json" | jq -r '.result[0].id')
|
||||
|
||||
# Create A record
|
||||
curl -s -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" \
|
||||
-H "Authorization: Bearer <CLOUDFLARE_API_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
--data '{"type":"A","name":"<subdomain>","content":"<IP_ADDRESS>","ttl":1,"proxied":false}'
|
||||
```
|
||||
**Common DNS Issues:**
|
||||
- Local DNS caching: Add entry to `/etc/hosts` temporarily for testing
|
||||
- Cloudflare proxy can cause SSL/TLS handshake failures - use non-proxied (grey cloud) records for direct server access
|
||||
- Use Cloudflare's proxy IPs directly if DNS propagation is slow
|
||||
|
||||
8. **Process Improvement**
|
||||
- After successful deployment, propose 3 new tools to add to agents.md.
|
||||
|
||||
### Useful Commands
|
||||
### DNS Management
|
||||
|
||||
Create A record via Cloudflare API:
|
||||
```bash
|
||||
# Check generated configuration before deployment
|
||||
nix eval '.#nixosConfigurations.<system>.config.services.<service>.enable'
|
||||
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')
|
||||
|
||||
# List systemd services from new config
|
||||
ls /nix/store/<path>-nixos-system-<system>/etc/systemd/system/*.service
|
||||
|
||||
# Test nginx configuration
|
||||
ssh <hostname> 'nginx -t'
|
||||
|
||||
# Check ACME certificate status
|
||||
ssh <hostname> 'ls -la /var/lib/acme/<domain>/'
|
||||
|
||||
# Verify certificate issuer
|
||||
openssl s_client -connect <domain>:443 | openssl x509 -noout -issuer
|
||||
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 to machines using hostnames (resolve via local `/etc/hosts` or DNS):
|
||||
```bash
|
||||
ssh <hostname> # Replace with actual system name
|
||||
ssh <hostname>
|
||||
```
|
||||
|
||||
### Make Configuration Changes
|
||||
1. **Check current systems:** View `flake.nix` for available system configurations
|
||||
2. **Edit local config:** `cd ~/src/nixos && vim [relevant_file]`
|
||||
3. **Test build:** `nixos-rebuild build --flake .#<system-name>`
|
||||
4. **Commit and push changes:**
|
||||
```bash
|
||||
git add . && git commit -m "description"
|
||||
git push origin master
|
||||
```
|
||||
5. **Update target systems:**
|
||||
```bash
|
||||
ssh <hostname> 'cd ~/src/nixos && git pull && sudo nixos-rebuild switch --flake .#'
|
||||
```
|
||||
```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
|
||||
# Update multiple systems
|
||||
for host in host1 host2 host3; do
|
||||
ssh $host 'cd ~/src/nixos && git pull && sudo nixos-rebuild switch --flake .#' &
|
||||
done
|
||||
wait # Wait for all updates to complete
|
||||
wait
|
||||
```
|
||||
|
||||
### Quick Management
|
||||
### Useful Commands
|
||||
```bash
|
||||
# Check service status
|
||||
ssh <hostname> 'systemctl status <service>'
|
||||
|
|
@ -166,18 +140,16 @@ ssh <hostname> 'systemctl status <service>'
|
|||
# View logs
|
||||
ssh <hostname> 'journalctl -u <service> -f'
|
||||
|
||||
# Rebuild if build fails
|
||||
ssh <hostname> 'cd ~/src/nixos && git pull && sudo nixos-rebuild switch --flake .#'
|
||||
# Test nginx config
|
||||
ssh <hostname> 'nginx -t'
|
||||
|
||||
# Test site availability via IP
|
||||
ssh <hostname> 'curl -k -I https://localhost:<port>'
|
||||
# Check ACME certs
|
||||
ssh <hostname> 'ls -la /var/lib/acme/<domain>/'
|
||||
|
||||
# Test site availability
|
||||
curl -I https://<IP> -H "Host: <domain>"
|
||||
|
||||
# Get public IP
|
||||
curl -s https://api.ipify.org
|
||||
```
|
||||
|
||||
### Repository
|
||||
- **Central:** https://git.symbiotrip.com/jsutter/nixos
|
||||
- **Config reference:** Check `flake.nix` for system names and module structure
|
||||
- **Update workflow:** Local edit → Push → Remote pull → Rebuild
|
||||
## Repository
|
||||
- **Central**: https://git.symbiotrip.com/jsutter/nixos
|
||||
- **Update workflow**: Local edit → Push → Remote pull → Rebuild
|
||||
Loading…
Add table
Add a link
Reference in a new issue