This guide provides a comprehensive understanding of the NixOS configuration for the snek.cc server. It combines conceptual explanations with practical, copy-pasteable examples so you can both understand why things are configured the way they are and actually implement them.
If you want to get started immediately without reading all the theory:
1. Prerequisites and Setup - Set up your server and DNS
2. Minimal Examples - Follow the step-by-step templates to go from zero to working system
3. Service Recipes - Add specific services with copy-pasteable configurations
4. Wafrn Setup - Add Wafrn fediverse instance (optional)
5. Troubleshooting - Fix common issues
1. Read 01-02 for concepts
2. Read 03-10 for service architecture
3. Follow 15 for hands-on practice
4. Reference 17 when adding services
5. Use 14 when things break
1. Complete 00 (setup)
2. Follow 15 step-by-step (implementation)
3. Use 17 to add desired services
4. Check 14 if you encounter issues
1. Ensure 15 Phases 0-2 are complete
2. Go to 17 and find your service recipe
3. Follow the recipe
4. Verify using recipe's checklist
Before reading this guide, you should have:
To recreate this setup, you'll need:
Server Requirements:
Domain & DNS:
snek.cc)*.snek.cc → server IP)Local Machine:
See Prerequisites and Setup for detailed setup instructions.
1. Declarative over imperative - Describe what you want, not how to get there
2. Purity and reproducibility - Same inputs always produce same outputs
3. Composition over monoliths - Small, focused modules combine into complex systems
4. Activation vs build time - Some things happen when Nix builds, others when the system activates
5. Secrets are special - They need special handling because they can't be in the Nix store
All configuration files live in /etc/nixos/:
/etc/nixos/
├── flake.nix # Entry point - defines system
├── flake.lock # Auto-generated - pins versions
├── configuration.nix # Your system configuration
├── hardware-configuration.nix # Auto-generated - hardware settings
├── secrets/ # Encrypted secrets
│ ├── .sops.yaml # Encryption config
│ └── *.yaml # Encrypted secret files
├── grafana-dashboards/ # Dashboard JSON files
└── guide/ # This documentation
}}}
== Important Notes ==
- *Never edit `hardware-configuration.nix`* - It's auto-generated
- *Never commit unencrypted secrets* - Always use sops
- *Test with `nixos-rebuild test` first* - Before using `switch`
- *Keep backups* - Especially of `/var/lib/` directories
- *Read logs* - `journalctl -u service-name -f` is your friend
== References and Citations ==
This guide draws from the following authoritative sources:
=== NixOS Documentation ===
- [[https://nixos.org/manual/nixos/stable/|NixOS Manual]] - Official NixOS documentation
- [[https://wiki.nixos.org/wiki/NixOS_Installation_Guide|NixOS Installation Guide]] - Step-by-step installation instructions
- [[https://wiki.nixos.org/|NixOS Wiki]] - Community-contributed documentation
- [[https://nix.dev/|nix.dev]] - Official documentation for Nix ecosystem
=== AT Protocol ===
- [[https://atproto.com/|AT Protocol Documentation]] - Official AT Protocol site
- [[https://atproto.com/guides/self-hosting|PDS Self-Hosting Guide]] - Official Bluesky PDS setup documentation
- [[https://atproto.com/guides/going-to-production|Going to Production]] - Production deployment best practices
=== Caddy Web Server ===
- [[https://caddyserver.com/docs/|Caddy Documentation]] - Official Caddy documentation
- [[https://caddyserver.com/docs/quick-starts/reverse-proxy|Reverse Proxy Quick Start]] - Caddy reverse proxy guide
=== Additional Tools ===
- [[https://github.com/Mic92/sops-nix|sops-nix]] - Secrets management for NixOS
- [[https://tailscale.com/kb/|Tailscale Documentation]] - VPN and networking
- [[https://prometheus.io/docs/|Prometheus Documentation]] - Monitoring and alerting
- [[https://grafana.com/docs/|Grafana Documentation]] - Data visualization