readme docs

2026-03-13 16:59:54 +01:00 · 2026-03-13 16:59:54 +01:00 · 9466ab3656
commit 9466ab3656
parent 6e0d407b1c
6 changed files with 1872 additions and 53 deletions
--- a/hosts/git/README.md
+++ b/hosts/git/README.md
@ -0,0 +1,210 @@
+# Git Host - Forgejo
+
+Forgejo git server at 141.56.51.7 running in an LXC container.
+
+## Overview
+
+- **Hostname**: git
+- **FQDN**: git.adm.htw.stura-dresden.de
+- **IP Address**: 141.56.51.7
+- **Type**: Proxmox LXC Container
+- **Services**: Forgejo, Nginx (reverse proxy), OpenSSH
+
+## Services
+
+### Forgejo
+
+Forgejo is a self-hosted Git service (fork of Gitea) providing:
+- Git repository hosting
+- Web interface for repository management
+- Issue tracking
+- Pull requests
+- OAuth2 integration support
+
+**Configuration**:
+- **Socket**: `/run/forgejo/forgejo.sock` (Unix socket)
+- **Root URL**: https://git.adm.htw.stura-dresden.de
+- **Protocol**: HTTP over Unix socket (Nginx handles TLS)
+
+### Nginx
+
+Nginx acts as a reverse proxy between the network and Forgejo:
+- Receives HTTPS requests (TLS termination)
+- Forwards to Forgejo via Unix socket
+- Manages ACME/Let's Encrypt certificates
+- WebSocket support enabled for live updates
+
+### OAuth2 Auto-Registration
+
+OAuth2 client auto-registration is enabled:
+- `ENABLE_AUTO_REGISTRATION = true`
+- `REGISTER_EMAIL_CONFIRM = false`
+- Username field: email
+
+This allows users to register automatically via OAuth2 providers without manual approval.
+
+## Deployment
+
+See the [main README](../../README.md) for deployment methods.
+
+### Initial Installation
+
+**Using nixos-anywhere:**
+```bash
+nix run github:nix-community/nixos-anywhere -- --flake .#git --target-host root@141.56.51.7
+```
+
+**Using container tarball:**
+```bash
+nix build .#containers-git
+scp result/tarball/nixos-system-x86_64-linux.tar.xz root@proxmox-host:/var/lib/vz/template/cache/
+pct create 107 /var/lib/vz/template/cache/nixos-system-x86_64-linux.tar.xz \
+  --hostname git \
+  --net0 name=eth0,bridge=vmbr0,ip=141.56.51.7/24,gw=141.56.51.254 \
+  --memory 2048 \
+  --cores 2 \
+  --rootfs local-lvm:8 \
+  --unprivileged 1 \
+  --features nesting=1
+pct start 107
+```
+
+### Updates
+
+```bash
+# From local machine
+nixos-rebuild switch --flake .#git --target-host root@141.56.51.7
+
+# Or use auto-generated script
+nix run .#git-update
+```
+
+## Post-Deployment Steps
+
+After deploying for the first time:
+
+1. **Access the web interface:**
+   ```
+   https://git.adm.htw.stura-dresden.de
+   ```
+
+2. **Complete initial setup:**
+   - Create the first admin account via web UI
+   - Configure any additional settings
+   - Set up SSH keys for git access
+
+3. **Configure OAuth2 (optional):**
+   - If using an external identity provider (e.g., authentik)
+   - Add OAuth2 application in the provider
+   - Configure OAuth2 settings in Forgejo admin panel
+   - Auto-registration is already enabled in configuration
+
+4. **Set up repositories:**
+   - Create organizations
+   - Create repositories
+   - Configure access permissions
+
+## Integration with Proxy
+
+The central proxy at 141.56.51.1 handles:
+- **SNI routing**: Inspects TLS handshake and routes HTTPS traffic for git.adm.htw.stura-dresden.de
+- **HTTP routing**: Routes HTTP traffic based on Host header
+- **ACME challenges**: Forwards `/.well-known/acme-challenge/` requests to this host for Let's Encrypt verification
+- **Auto-redirect**: Redirects HTTP to HTTPS (except ACME challenges)
+
+This host handles its own TLS certificates via ACME. The proxy passes through encrypted traffic without decryption.
+
+## Troubleshooting
+
+### Forgejo socket permissions
+
+If Forgejo fails to start or Nginx cannot connect:
+
+```bash
+# Check socket exists
+ls -l /run/forgejo/forgejo.sock
+
+# Check Forgejo service status
+systemctl status forgejo
+
+# Check Nginx service status
+systemctl status nginx
+
+# View Forgejo logs
+journalctl -u forgejo -f
+```
+
+**Solution**: Ensure the Forgejo user has proper permissions and the socket path is correct in both Forgejo and Nginx configurations.
+
+### Nginx proxy configuration
+
+If the web interface is unreachable:
+
+```bash
+# Check Nginx configuration
+nginx -t
+
+# View Nginx error logs
+journalctl -u nginx -f
+
+# Test socket connection
+curl --unix-socket /run/forgejo/forgejo.sock http://localhost/
+```
+
+**Solution**: Verify the `proxyPass` directive in Nginx configuration points to the correct Unix socket.
+
+### SSH access issues
+
+If git operations over SSH fail:
+
+```bash
+# Check SSH service
+systemctl status sshd
+
+# Test SSH connection
+ssh -T git@git.adm.htw.stura-dresden.de
+
+# Check Forgejo SSH settings
+cat /var/lib/forgejo/custom/conf/app.ini | grep -A 5 "\[server\]"
+```
+
+**Solution**: Ensure SSH keys are properly added to user accounts and SSH daemon is running.
+
+### ACME certificate issues
+
+If HTTPS is not working:
+
+```bash
+# Check ACME certificate status
+systemctl status acme-git.adm.htw.stura-dresden.de
+
+# View ACME logs
+journalctl -u acme-git.adm.htw.stura-dresden.de -f
+
+# Manually trigger certificate renewal
+systemctl start acme-git.adm.htw.stura-dresden.de
+```
+
+**Solution**: Verify DNS points to proxy (141.56.51.1) and proxy is forwarding ACME challenges correctly.
+
+## Files and Directories
+
+- **Configuration**: `/nix/store/.../forgejo/` (managed by Nix)
+- **Data directory**: `/var/lib/forgejo/`
+- **Custom config**: `/var/lib/forgejo/custom/conf/app.ini`
+- **Repositories**: `/var/lib/forgejo/data/gitea-repositories/`
+- **Socket**: `/run/forgejo/forgejo.sock`
+
+## Network
+
+- **Interface**: eth0 (LXC container)
+- **IP**: 141.56.51.7/24
+- **Gateway**: 141.56.51.254
+- **Firewall**: Ports 22, 80, 443 allowed
+
+## See Also
+
+- [Main README](../../README.md) - Deployment methods and architecture
+- [Proxy README](../proxy/README.md) - How the central proxy routes traffic
+- [Forgejo Documentation](https://forgejo.org/docs/latest/)
+- [NixOS Forgejo Options](https://search.nixos.org/options?query=services.forgejo)