Add SD image pipeline, documentation overhaul, and fix module issues

- Add automatic SD image builds for Raspberry Pi via Forgejo Actions
- Enable binfmt emulation on cryodev-main for aarch64 cross-builds
- Add sd-image.nix module to cryodev-pi configuration
- Create comprehensive docs/ structure with installation guides
- Split installation docs into: first-install (server), reinstall, new-client (Pi)
- Add lib/utils.nix and apps/rebuild from synix
- Fix headplane module for new upstream API (tale/headplane)
- Fix various module issues (mailserver stateVersion, option conflicts)
- Add placeholder secrets.yaml files for both hosts
- Remove old INSTRUCTIONS.md (content moved to docs/)
This commit is contained in:
steffen 2026-03-11 08:41:58 +01:00
parent a5261d8ff0
commit 5ba78886d2
44 changed files with 3570 additions and 609 deletions

116
docs/services/headscale.md Normal file
View file

@ -0,0 +1,116 @@
# Headscale
Headscale is an open-source, self-hosted implementation of the Tailscale control server.
## References
- [Website](https://headscale.net/stable/)
- [GitHub](https://github.com/juanfont/headscale)
- [Example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml)
## Setup
### DNS
Set a CNAME record for `headscale.cryodev.xyz` pointing to your main domain.
### Configuration
```nix
# hosts/cryodev-main/services/headscale.nix
{
services.headscale = {
enable = true;
openFirewall = true;
};
}
```
## Usage
### Create a User
```bash
sudo headscale users create <USERNAME>
```
### List Users
```bash
sudo headscale users list
```
### Create Pre-Auth Key
```bash
sudo headscale preauthkeys create --expiration 99y --reusable --user <USER_ID>
```
The pre-auth key is used by clients to automatically authenticate and join the tailnet.
### List Nodes
```bash
sudo headscale nodes list
```
### Delete a Node
```bash
sudo headscale nodes delete -i <NODE_ID>
```
### Rename a Node
```bash
sudo headscale nodes rename -i <NODE_ID> new-name
```
## ACL Configuration
Access Control Lists define which nodes can communicate with each other.
### Validate ACL File
```bash
sudo headscale policy check --file /path/to/acl.hujson
```
### Example ACL
```json
{
"acls": [
{
"action": "accept",
"src": ["*"],
"dst": ["*:*"]
}
]
}
```
## Troubleshooting
### Check Service Status
```bash
sudo systemctl status headscale
```
### View Logs
```bash
sudo journalctl -u headscale -f
```
### Test DERP Connectivity
```bash
curl -I https://headscale.cryodev.xyz/derp
```
## Integration
- [Headplane](headplane.md) - Web UI for managing Headscale
- [Tailscale Client](tailscale.md) - Connect clients to Headscale